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About This Manual 



This manual includes: 

— an overview of how each part of the Canon Cat software works 

— a detailed step-by-step explanation of routines and data structures 

— a summary of routines and integers 

To understand the Cat software, you will also need the tForth Manual. 

The software was written in the programming language tForth, a 
version of Forth developed at Information Appliance. The software was 
developed on early models of the Cat itself. In the production model, 
the software is stored in ROM. 

Important: This editor features a user interface designed for speed and 
ease of use. All modifications and extensions must conform to its 
design principles and style in order to maintain user interface integrity. 
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Part I. Editor Basics 



t) Pointers and Data structures 1 



The central data structure in the Cat is the 
text, which is supported by various pointers 
and tables. Characters flow into the text 
through the keyboard, and are in turn 
displayed on the screen. The screen has 
two parts: the text occupies most of the 
screen, and the ruler and status line appear 
at the bottom. 
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Part II. Text Commands f 

The basic commands affect the style of the 

text or the position of the cursor. Style and D 
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highlight, paragraph or document. Leap and 

Drag move the cursor. Copyup duplicates 

text onto another disk. D 

The Undo command is defined as part of 

other commands, so does not have a 'fl© 

separate chapter here. The Answer 

command is not described in this manual till 

because it is so rarely used. 
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command. Explain, Titles and Set Up write 
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HOW TO INTEGRATE SOFTWARE INTO THE CANON CAT 



Products designed by Information Appliance Inc. (IAI) , such as 
the Canon Cat, have a number of unique features. One of them 
that directly affects third-party software development is the 
principle of editor-based software. 

In most microprocessor-based products, the user shifts between 
applications by returning to the operating system, indicated by a 
menu with a number of choices (or, equivalently, a window with a 
number of icons.) Then the user chooses the next application. 
Once having entered the application, the user gets the data on 
which to work. 

In an IAI interface, the data stays in place at all times so that 
the user can concentrate on content rather than on the system. 

As commands are given, different "applications" come to bear on 
the user's text or graphics (there are graphics primitives in the 
Cat, although the built-in software does not use them). This is 
possible due to our unified data structure which is -- all at the 
same time ~~ a text, a data base, a spreadsheet, and a 
programming environment. 

The user has a much simpler mental model with the IAI interface 
than with traditional products, since invoking an application 
looks just like another simple editor command. The user does not 
have to work with a number of different editors, one for each 
application. This is an improvement over the Macintosh, for 
example, in that with the Macintosh model each application must 
recreate (using provided routines) an interface that is similar 
to that of other applications. 

When developing new applications for the Cat, it is easiest, both 
on the programmer and the user, to make your application look 
just like the existing built-in software. When your application 
needs to get information from the user, it generally asks a 
question. This can be done by sending the question to the 
screen, perhaps surrounded by a few blank lines so that it is 
visible. If the user finds that the question has come out in an 
awkward place (say, in the middle of a letter) , then the user can 
always delete the question or move it elsewhere. 

A typical question for an accounting package might be: 

Name of account? 

When this appears, the application should wait for a response to 
be sent to it by the ANSWER command (USE FRONT-ERASE) . Thus the 
user is free to employ any and all the features of the Cat in 
creating the answer, for example, they might leap to their 
account area, or even change disks or perform a calculation to 
find the information they need. The idea here is to leave the 
full power of the Cat available at all times. 
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When the user has formulated the answer to the question your 
application has asked, they highlight it and use the ANSWER 
command. At this point, your application is in control again and 
can do what it wishes until it asks its next question. 

This "loss of control" after a question has been asked will 
disturb some designers who are used to a forcefully directed 
dialog with the user. However, research has shown that users 
work better if they can do tasks at their own speed, and if they 
are in control. There is nothing more annoying than a program 
that demands an answer and won’t let you use the system (say for 
looking up a phone number you need right now) until you are 
finished answering the computer’s question -- a task that might 
take a few minutes if you have to look up something that's in a 
file cabinet somewhere. 

One secret of the Cat's utility is that all abilities are 
available simultaneously and instantaneously. If your 
application has a number of features or areas, then allow the 
user to create a message which activates them when desired (the 
messages sent to your application via the ANSWER command, of 
course. One set of messages might be: "AR" to activate the 
accounts receivable package, "AP" to activate the accounts 
payable package, and "GL" to run the general ledger package. 

Once in any of these packages, the dialog would work as already 
described. 

Notice that you do not have to write any I/O editing routines. 

You can simply send strings to the screen, and receive strings 
(edited by the user) . Naturally, your application may need to do 
error checking, but when an error is detected, you can just send 
a string to the screen with the message, the user can edit their 
previous response using the Cat's built-in editor, and resend it 
to your application. 

Following this protocol will keep the Cat feeling like a Cat, and 
will be least disruptive to a user's habits. It is also very 
easy and quick to create application interfaces this way. 

Jef Raskin 
13 September 1988 




ENABLING FORTH IN THE CAT 



Forth is normally hidden away, inaccessible in the Cat. However, 
with a simple incantation you can ’’enable Forth,” making it 
possible to switch from the Cat's editor to a Forth programming 
environment, or to run Forth programs from the Cat's editor with 
the ANSWER command. Forth enablement is associated with a given 
disk and text. If you enable Forth, record the text, change to a 
non-enabled disk, then Forth will no longer be enabled. 

Remember to exercise caution whenever Forth has been enabled. 

For example, a nonprogrammer may be trapped in Forth if they 
accidentally press the key combination SHIFT-USE FRONT-SPACE BAR 
while editing the text on a Forth-enabled disk. The key 
combination USE FRONT- SEMI -COLON will erase the disk in the drive 
if Forth is enabled. Other pitfalls exist. SO, PROCEED WITH 
CAUTION IF YOU ENABLE FORTH. READ THE DISCLAIMER AT THE 
BEGINNING OF THE MANUAL. 

HOW TO TURN ON FORTH 

We will now explain how to turn on Forth, and, equally important, 
how to turn it off: 

1. To turn on Forth in a Cat, type the following phrase (be sure 
to capitalize ”E”, ”F”, and ”L”}: 

Enable Forth Language 

2. Highlight these three words. 

3. Hold down the USE FRONT key and, while holding it, tap the 
ANSWER key (ERASE). Then let go. This executes the ANSWER 
command, enabling Forth. You are not yet in Forth. 

4. Now hold down the USE FRONT key AND the SHIFT key, and, while 
holding BOTH keys, tap the SPACE BAR. You are now in the 
Cat’s Forth editor. 

5 . Type the following and press the RETURN key (the letters will 
automatically appear in boldface): 

-1 wheel! savesetup re 

This step allows you to enter Forth simply by pressing 
SHIFT-USE FRONT-SPACE BAR from now on. 

To enable easy access to Forth with Step 4 only, make some 
change to a Setup parameter, then use the DISK command. This 
will save the Forth enabling information on the disk. 

Whenever you play back this disk, you can then enter Forth 
using only the procedure of Step 4. 
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6. To turn off Forth, type the following and press RETURN key: 



Forth? off 0 wheel! re 

Make some change to a Setup parameter, then use the DISK 
command. This restores the Cat to normal operation, meaning 
that you will have to start over at step 1 again to invoke 
Forth. Normal Cat users will not be trapped in Forth in case 
they happen to accidentally press SHIFT-USE FRONT-SPACE BAR. 

TALKING TO t FORTH 

tForth is hiding in the background of every Cat system. It is 
very easy and convenient to communicate with tForth from within 
the editing environment. 

SENDING COMMANDS TO tFORTH 

Once Forth has been enabled (see the previous page) , commands and 
programs can be sent to tForth from the editor by highlighting 
the desired command string or program listing and pressing 
[ERASE] while holding the [USE FRONT] key down. tForth 's 
responses will be printed out in the editor. 

All examples in this manual are expected to be typed into the 
editor and "sent” to tForth in this manner. All examples 
presented are set off from the body of the text by two blank 
lines and are indented: 

3 dup ..33 

A section of the above example was underlined. In an example, 
the underlined sections are the sections of the text which should 
be highlighted and passed to tForth by pressing the [USE 
FRONT] [RETURN] key combination. After the above example was sent 
to tForth, tForth responded by printing two 3’s on the screen. 

USING THE CALC COMMAND TO TALK TO tFORTH 

Commands and programs can also be sent to tForth with the use of 
the [USE FRONT] [CALC] key combination. When this method is 
used, all command strings or program listings sent to tForth must 
be preceded by a "]” character: 

]3 dup ..33 

The above example produced the same results as the [USE FRONT] 
[RETURN] example. The [USE FRONT] [CALC] method is not used in 
this manual. 
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ERRORS 



The [USE FRONT] [RETURN] is used to let Forth know it should start 
’processing’ any highlighted words. If Forth ever has a problem 
processing an input, a beep will be issued. To see the error 
message press the [EXPLAIN] key while holding the [USE FRONT] key 
down. For example, if tForth is sent the following input: 

How now brown cow? 

it will beep and [USE FRONT] [EXPLAIN] will reveal a ’’can't use” 
message. This is the error message which occurs when tForth is 
sent a command it does not recognize. 

CAUTION: ALWAYS RECORD YOUR EDITOR TEXT ON DISK BEFORE DIRECT 

EXECUTION OF tFORTH WORDS. IT IS VERY EASY TO MAKE PROGRAMMING 
MISTAKES WHICH COULD PERMANENTLY DAMAGE THE DOCUMENT. 
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A BRIEF INTRODUCTION TO FORTH 



The Forth language is comprised of many "words” (commands) . This 
collection of words is referred to as the "Forth dictionary." 

The tForth dictionary contains approximately 600 words. The list 
below shows a few Forth words and the actions they perform: 

emit Takes a number and displays the corresponding 

ASCII character on the screen. 

+ Adds two numbers together and returns the 

result. 

words Produces a listing of all available words. 

if Words used to implement the IF. . .THEN 

then program control construct. 

@ Fetches a 32-bit value from memory. 



As the list shows, a Forth word can either have the format of a 
"normal" word (a sequence of letters), or it can be a punctuation 
mark, a sequence of punctuation marks, or a mixture of 
punctuation marks and characters. In a Forth program, all words 
must be separated from each other by at least one space, tab, or 
carriage return. In this document Forth commands will be shown 
in boldface. For example: 

"The Forth word words will produce a listing of all available 
words . " 

Note: tForth is case-sensitive. This means that tForth thinks a 

capital W is different than a lowercase w. Thus tForth will 
think Words is a different command than words. 

If the pronunciation of a Forth word is unclear, it's first usage 
in the text will be followed by the natural language 
pronunciation enclosed in quotes and parentheses. For example: 

To take a number off of the parameter stack 
and display it, use the word . ("dot"). 

EXECUTING A FORTH WORD 

Most of the words in the Forth dictionary may be executed 
directly and immediately, from the keyboard. The example below 
shows how the Forth word emit could be used to display an 
asterisk character on the screen. In the example, the underlined 
type is used to indicate which commands should be highlighted and 
sent to tForth. The normal type is used to show Forth's 
responses . 
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ERRORS 



The [USE FRONT] [RETURN] is used to let Forth know it should start 
’processing’ any highlighted words. If Forth ever has a problem 
processing an input, a beep will be issued. To see the error 
message press the [EXPLAIN] key while holding the [USE FRONT] key 
down. For example, if tForth is sent the following input: 

How now brown cow? 

it will beep and [USE FRONT] [EXPLAIN] will reveal a ’’can't use" 
message. This is the error message which occurs when tForth is 
sent a command it does not recognize. 

CAUTION: ALWAYS RECORD YOUR EDITOR TEXT ON DISK BEFORE DIRECT 

EXECUTION OF tFORTH WORDS. IT IS VERY EASY TO MAKE PROGRAMMING 
MISTAKES WHICH COULD PERMANENTLY DAMAGE THE DOCUMENT. 
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Note: Do not confuse the underlined commands in the examples 

with the underlined Forth words in the text. In the examples the 
underlined commands are those commands which should be 
highlighted and sent to tForth with the ANSWER command. 

42 emit # 

emit , as was described above, is a Forth word which will display 
the character which corresponds to the ASCII value passed to it. 

COMPILING FORTH WORDS 

The interactive execution of emit in the previous example did not 
cause any code to compiled. The Forth word : ("colon") is used 
to turn the Forth compiler on: 

: printstar 42 emit ; 

The above example shows how a new word may be added to the Forth 
dictionary. The word which immediately follows : (printstar 

in the above example) is the name which will be assigned to the 
new word. The Forth words following the name and preceding the 
; will be compiled into the new definition; these are the words 
which define the actions of the new word. Since the action words 
for printstar are 42 emit, printstar will print an asterisk when 
executed. The word ; ("semi-colon") is used to turn the compiler 
off and return to the interactive execution mode. 

Note that in this example, sending the input to Forth did not 
cause the asterisk to be displayed. Since the Forth compiler was 
"on" when the "42 emit" was typed, the 42 emit was compiled 
rather than executed. Forth was able to successfully compile the 
new definition so no error beep was issued. Forth is an 
"incremental compiler"; code is compiled definition by 
definition; compilation is triggered by each reception of a line 
of input. 

THE FORTH PARAMETER STACK 

Forth is a stack-based language. Any Forth word which takes an 
input will expect to find its input paramete on the Forth 
parameter stack when it executes. Any Forth word which returns a 
value will leave the value on the parameter stack when it 
completes execution. 

The parameter stack, and stacks in general, are functionally 
similar to the spring-loaded stack of plates which can be found 
at most institutional kitchens. Whenever a plate is taken from 
the stack, it is always taken from the top of the stack of 
plates. Whenever a plate is added to the stack, it is always 
added to the top of the stack of plates. A person who does not 
want the steaming hot plate on top of the stack must remove the 
top plate before the second plate can be accessed. If no plates 
are available, the stack is empty. 
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The Forth parameter stack works the same way as the stack of 
plates, except the Forth parameter stack is set up to hold 
numeric values rather than plates. Also, just as the kitchen 
stack was designed for a certain plate size, the Forth parameter 
stack is designed for a certain numeric value size (the plate 
size of the tForth parameter stack will be discussed later) . 

INTERACTING WITH THE PARAMETER STACK 

To put a number on the parameter stack, send the number to Forth: 

34 

To take a number off the parameter stack, use the word drop. To 
take a number off the parameter stack and display it, use the 
word . ("dot"): 



. 34 

To place more than one number at a time on the stack, send the 
numbers, separated from each other by a space or spaces (so that 
Forth knows they are distinct numbers) , to Forth: 

3 6 8 

Now there are three numbers on the stack. If . is used, it will 
take the top number off the stack and display it. Since the 8 
was the last value placed on the stack, it will be the top value 
on the stack: 

. 8 

To place more than one number on the stack at a time, the numbers 
were separated by spaces and sent to Forth. This is the same way 
Forth commands (words) work. To take both of the remaining 
numbers off the stack, the word . can be used twice on the same 
line : 



-.63 

Forth's response should be read left to right. The 6 is the 
result of the first use of . The 3 is the result of the second 
use of 

Note what happens if . is used again: 

. 0 

You should hear a beep as . tried to remove a value from an 
empty stack and Forth responded by displaying a zero, beeping and 
issuing a "stack is empty" error message. 
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PASSING PARAMETERS TO FORTH WORDS ON THE STACK 



Many Forth words take input parameters from the stack and return 
results on the stack. The Forth word + (''plus") is a good 
example of such a word: 

5 4 + . 9 

♦ takes two numbers from the stack (the 5 and the 4 in the above 
example) , adds them together and returns the single number result 
on the stack. In the example, . was use to display the result 
returned by + 

SUMMARY 

* Forth programs are developed by creating new 
words out of previously existing words. 

* The parameter stack is the primary means of 
communication among Forth words. 

* The Forth language does not have many syntax 
requirements. This gives the experienced programmer 
great control over the computer but can make it 
difficult for beginning programmers to locate mistakes. 

* The interactive abilities of Forth make it a hard-to-beat 
debugging environment. Each word can be tested 
individually and interactively. 

This is the end of our brief introduction to the Forth language. 
For more introductory Forth reading, refer to the first chapter 
of Starting Forth , by Leo Brodie (Prentice-Hall, Inc., Englewood 
Cliffs, NJ 07632, 1981). 
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CONVENTIONS 



Convention 
Boldf ace 
Underline 



Meaning 



Example 



Meaning of Example 



Forth 



LBPfix The Forth word "LBPfix" 



Variable 



Hex 



n choices An as yet 

unspecified number 
of choices, to be 
fixed when the given 
operation is carried 
out. 

$4E "4E" is a hex number. 



x 




1. POINTERS AND DATA STRUCTURES 



Introduction 



The data maintained by the Cat editor is kept in an area called 
the text . The addresses of important areas or locations in the 
text are kept in many system integers. The basic data structure 
used to hold formatting information about the text is called a 
control/format array . The three main data structures used to 
maintain the text, the #ctrl array, the window table, and the 
interval table are each comprised of one or more control/format 
arrays . 





1.0 THE TEXT 



1.0.0 What It Is 

The text contains all of the characters, calculations, and 
formatting information the user enters into the editing 
environment. The text contains several types of organized data: 

ASCII character codes 
character attribute information 
paragraph format information 
- document format information 
calculation data 

The editor's only function is to alter, maintain, and display 
this data. This section of the manual will discuss the lower 
level constructs which allow the editor to function properly and 
quickly . 

To manage the text within its allocated area of memory, the 
editor relies upon many system integers which contain pointers to 
key locations in the text. Examples of key locations are 

where the text starts and ends 

which character in the text the cursor is currently over 
where new characters typed in by the user should be inserted. 

The editor data structures give meaning to the text data. The 
fields in the data structures give the editor information on how 
the character data should be displayed. 



1.0.1 Where It Is 



The text is located in the Cat's RAM space. The current Cat 
system has 3&4K of RAM located starting at address $400,000. The 
following diagram (1.1) shows where in the RAM space the text is 
located . 
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1.1 Cat RAM Allocations 




$400000 $420000 



$460000 



- 3 - 






1.1 POINTERS USED TO MAINTAIN THE TEXT 



The following diagram (1.2) shows a close-up of the text area and 
describes some of the pointers used to maintain the RAM text area. 



1.1.0 The Beginning of the Text Area 

The text system integer holds the address of the very first byte 
of text data in the first text partition. The bot, or 
beginning-of-text , system integer holds the address of the first 
byte of the user’s text data. The memory between the two 
addresses is used as a buffer zone between the start of the 
allocated text area and the start of the actual text data. The 
start buffer zone is filled with eight carriage return characters. 



1.1.1 The Start of the Gap Region 

The text data is broken into two pieces. Sandwiched between them 
is a region of memory referred to as the gap . All unused space 
allocated to text is located in the gap. 

The gap system integer holds the address of the start of the 
gap. The existence and location of the gap help contribute to 
the quick response of the editor in many situations. For 
example, the start of the gap is usually adjacent to the 
character in the text which is marked with the cursor. This 
means new characters typed in can be placed directly into the gap 
region and instantly appended to the end of the first partition 
of text without any movement of the rest of the text data. 

The bos, or beginning-of-selection , system integer holds the 
address of the first character in the current selection. If the 
selection is extended, that is, if more than one character is 
highlighted, bos will hold the address of the first highlighted 
character in the selection. If the selection is not extended 
(one character highlighted), and if the cursor is wide, bos will 
hold the address of the character seen in the non-blinking half 
of the cursor. When the cursor is narrow, the bos will hold the 
address of the character under the narrow cursor. When the 
selection is not extended the bos will point to the address of 
the last character in the first partition of text data, that is, 
the bos pointer and the gap pointer will be right next to each 
other (see the following diagram, 1.3) • 
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12 The Text 



...and the pointers used to maintain it. 



i 



v* 

» 



low high 



memory 


1st partition of text data 


...the gap... 


2nd partition of text data 


memory 






’ 
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t t 

text bot 



tt 

bos gap 



t tt 

bou eou beot 
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eos 



t t 

eot endtext 



integer name integer cont ent s 

text : address of the absolute start of the RAM text area. 

bot • address of start of user text data. 

bos : address of beginning of selection. 

gap : address just beyond end of first partition of text. 

bou : address of the beginning of the undo buffer. 

eou : address of the end of the undo buffer. 

eos : address of the end of selection. 

beot : address of the beginning of the end (2nd partition) of text, 

eot : address of the end of the user text data, 

endtext : address of the absolute end of the RAM text area. 




1.3 Cursor Logistics 



Wide cursor: 
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bos gap 
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eos & beot 



Narrow cursor: 
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Extended selection: 




t e s tin 




t 
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1.1.2 The Second Partition of Text Data 



The start address of the second text partition is held in the 
beot, or beginning-of-end-of-text , and eos, or end-of -selection , 
system integers. If the cursor is wide, eos will hold the 
address of the character under the blinking portion of the 
cursor. If the cursor is narrow, eos will hold the address of 
the character which immediately follows the narrow cursor. The 
words eos and beot hold the same address except while a Leap key 
is down and a successful leap is in progress; in other words 
while the cursor is no longer where it was when the Leap key was 
first held down (see the following diagram, 1.3). 

The eot, or end-of-text , system integer holds the address of the 
last byte of user text data in the second text partition. The 
endtext system integer holds the address of the last memory 
location in the RAM text area. The area between the eot and 
endtext pointers forms a buffer area between the end of the 
user’s text and the absolute end of the RAM text area. The end 
text buffer holds 30 carriage return characters. 



1.1.3 The Undo, or "Cut" Buffer 

The last area of interest in the RAM text area is the undo buffer 
area. The undo buffer is located in the gap region. The start 
address of the undo buffer is kept in the bou, or 
beginning-of-undo-buf f er , system integer. The eou, or 
end-of -undo-buffer , which is defined as 

: eou { -> a } beot 4 - ; 

is used to find the end of the undo buffer. The undo buffer is 
relocated whenever the eos position changes, that is, after a 
successful leap or creep. The undo buffer holds information 
(text, formatting info) required in order to undo an operation. 
Whenever information needs to be placed in the undo buffer the 
bou pointer is repositioned so that the undo buffer becomes just 
large enough to hold the desired information. 
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1.2 CONTROL /FORMAT ARRAY 



The control /format array is the basic structural unit used in the 
Cat editor. A single control/format array holds esize bytes of 
formatting information pertaining to a particular line in the 
text. The three main data structures used by the editor 
(described below) each consist of one or more control/format 
arrays . 

Three basic types of formatting information are kept in the 
control/format array: 

transient format information 
paragraph format information 
document format information 

The structure of a control/format array is shown in the following 
diagram (1.4). The names of the fields, their hexadecimal array 
offsets (in bytes), and a description of their contents are 
listed below. 

1.2.0 Transient Format Information 



Transient format information is volatile format information which 
must be "calculated 11 each time it is requested. The transient 
information in the control/format array can become obsolete as a 
result of a single character insertion or deletion. If a 
character insertion/deletion moves the cursor to a different line 
or page, the line and line start information, or page information 
will immediately become invalid. The contents of most of the 
transient format information fields are described sufficiently 
below. The use of the %spr field is explained in the section on 
text display. "Global" means relative the the bot. 



Name 


Offset 


Description 


£page 


00 


The global page number in which this line is 
located 


*Pgl 


04 


The local page number (within the current 
document) in which this line is located 


%wr 


08 


Address of the first character in this line 


%ln 


OC 


The global line number for this line 


%lnl 


10 


The local line number (within the current 
page) for this line 


%spr 


12 


Can hold one of four values: 0 , 1 , 2 , 3* 

Used by the words responsible for displaying 
lines of text 

0: Display a real line of text 
1: Do nothing 

2: Display one blank half-line 
3: Display one blank half-line 
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1.4 Control/Format Array 



Transient Format 
information 



Paragraph Format 
Information 



Document Format 
Information 



00 




%page 


02 


! 


%pgl 


04 




%wr 


08 




%ln 


0A 




%lnl 


OC 




%spr 



%lsp 

%oidlsp 

%l eft 

%wide 

%indent 

%iwida 

%just 



%tabs 



2A 




%long 


2B 




2C 




%above 


2D 




%below 


2E 




%iock 




:■ {unused) - • j 




30 




%ipage 


32 




%iprint 


34 


{unused} 




36 






Total = 38 hex bytes 


{unused} 









OE 

OF 

10 

11 

12 

13 

14 

16 
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1.2.1 Paragraph Format Information 



The paragraph format information fields hold values which control 
how the characters in the paragraph should be placed on the 
screen when they are displayed. A paragraph is a section of text 
surrounded by a break, that is, a carriage return, page break, or 
document break. For example, the £left field holds the width of 
the left margin, expressed in units of half spaces. The display 
routines will use the contents of the %left field when they need 
to determine where the first character on a line should be placed 



Name 


Offset 


Description ! 


%lsp 


14 


Local line spacing. Can hold one of three 
values: 2, 3» 4. Used by the words 

responsible for displaying lines of text 






2: Single-spaced text 

3: l£ spaced text 

4: Double-spaced text 


%left 


15 


Current left margin width, expressed in half 
spaces. 0 <= n <= 158 


#wide 


16 


Width of the text area, expressed in half 
spaces. 2 <= n <= 160 


^indent 


17 


Indent distance for this line, expressed in 
half spaces. 0 <= n <= 158 


£iwide 


18 


The width of the text area on an indented 
line 


jus t / 


y) 


Paragraph Style 


/ 

/ 


h 


0: Normal, left- justified, ragged right 

1: Right- justified , ragged left 

2: Centered, ragged left and right 

3: Justified left and right 


2 tabs 


1A 


Two 80-bit bit arrays. The screen is 80 



full spaces wide. The state of each bit in 
the first bit array indicates whether the 
corresponding space on the screen has a tab 
associated with it. The second bit array 
indicates whether the corresponding space 
has a decimal tab associated with it. 
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1.2.2 Units Used in the Control/Format Array 



1.2. 2.0 Vertical Positioning Units 

All vertical positioning of text is based on the unit of a 
half-line. Half-lines are 1/2 the thickness of a line of text. 
The Cat editor supports three types of line spacing: single, H, 
and double. Depending on the line spacing currently selected, 
zero, one, or two half-lines will be inserted between each 
displayed line. 

For example, in single-spaced text each line of text immediately 
follows the previous line of text; no half-lines are used in the 
display. In li-spaced text, one half-line is inserted between 
each line of text. In double-spaced text, each line of text is 
followed by two blank half-lines. 

Although the text may not appear to include half-lines -- single 
spaced text, for example -- the code always counts in half-lines 
when calculating positions in text. This provides fast access to 
display information about any point in text, which speeds up 
leaping. 

The Cat can display 22 lines of text at one time. Since each 
line of text is two half-lines wide, the screen can hold 44 
half-lines . 

1.2. 2.1 Horizontal Positioning Units 

Spaces and half-spaces determine the horizontal position of 
characters. Since the Cat editor uses a non-proportional font, 
each character in the character set has the same width, 8 
pixels. Thus a half-space is 4 pixels wide. Half-spaces are 
often inserted into in order to fully justify text. 



1.2.3 Document Format Information 



The document format information fields contain information about 
the document in which the line is located. Several of the fields 
(%above, Jtbelow, %iprint) hold information which will determine 
the printed appearance of the document. The contents of the 
*lock field indicate whether or not the line is alterable. If 
the document which contains the line is locked, the line cannot 
be altered. 
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Name Offset Description 



%long 2E 



The value stored in £long indicates how long 
a page should be before the Cat inserts an 
implicit page break. The page length is 
expressed in half-lines. 



Jtabove 30 



Holds the height of the top margin of a 
printed page expressed in half-lines 



Xbelow 31 



Holds the height of the bottom margin 
expressed in half-lines 



£lock 32 If this line is in a locked region, %lock 

will hold the ASCII value for the gray lock 
character. 



%ipage 34 First page number in the document 

£iprint 36 Number of the first printable page in the 

document 
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1.3 MAJOR DATA STRUCTURES 



1.3.0 The Control Table 

The control table (#ctrl) consists of one control/format array. 
The address of the control table is kept in the #ctrl system 
integer. The #ctrl is used as a scratch control/format array by 
routines which need a temporary location for the storage of 
control/format information. Control /format information which 
must be saved for future reference is usually moved from the 
#ctrl table to one of the other data structures described below. 

A backup control table, called the previous control table 
(#pctrl), holds the previous contents of the #ctrl table. The 
system integer #pctrl holds the address of the control/ format 
array for the preceding text line. This value is updated each 
time the word wrap is executed. 



1.3.1 The Window Table 

The window table (tfwtable) consists cf lastline ($4E) 
control/format arrays. Each controi/format array in the window 
table contains formatting information about one half-line 
currently displayed on the screen and about the half-lines just 
above or just below the top or bottom lines in the display. The 
following diagram (1.5) illustrates the connection between the 
window table and the text displayed on the screen. 

The 79 control/format arrays in the window table are shown on the 
right side of the diagram. The display text to which the 
control/ format arrays correspond are shown on the left side of 
the diagram. The number to the left of a displayed line of text 
is the number of the window table entry corresponding to the line 
of text. The numbers increment by two because two window table 
entries are required to represent lines of single-spaced text. 
(The display of single-, 1£, and double-spaced text is covered in 
detail in the "Text Display" section of this manual. 

The system integers firstseen ($10) and lastseen ($3B) hold the 
line numbers of the first and last visible half-lines represented 
in the window table. The system integer lastline holds the 
number of the last line represented in the window table. The 
address of the start of the window table is kept in the tfwtable 
system integer. The bytes in the window table can be calculated 
by lastline # esize: . 
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1.5 The Window Table 




#wtable 



GontroWormal 

arrays: 

(2 for each line 
of singie-spa^ed 
text). 






1 . 3*2 The Update Array 

The update array is closely related to the window table. The 
update array contains a 1-byte flag for each half-line 
represented in the window array. If a byte contains a non-zero 
value, the corresponding half-line in the display requires 
refreshing. If the byte contains a zero value, the corresponding 
half-line is properly displayed. 

When display routines are called to redraw the screen contents, 
they will usually check the update array first so that only the 
lines which require refreshing are redrawn. 



1.3.3 The Interval Table 

To allow quick display of any character in the text, the text 
data is divided into many equal-sized text intervals . Formatting 
information about a line of text within each interval is kept in 
a table called the interval table {see diagram 1.6). 

Currently the size of a single text interval is $400, or 1024 
decimal bytes. Since the entire text size in the editor can be 
either 256 K or 384 k bytes, the interval table will have either 
256 or 384 (decimal) entries. Each entry in the interval table 
is a control/format array which holds the formatting information 
about one line in the corresponding text interval . 
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1.6 Interval Table 





1.3. 3-0 How Control /Format Information Is Obtained 

To get the formatting information which applies to a line in the 
text one must step through the text data which contains the 
characters for the line, looking for and obtaining the 
user-specified formatting information hidden among the characters 
(document and paragraph format information set by the following 
commands: Line Spacing, Left Margin, Right Margin, Set/Clear 

Tab, Indent, and Setup). This process is called wrapping through 
the text because the fundamental task is to determine implied 
word wrap. 

wrap is the editor word which examines a line of text and 
produces a set of control/format information for the line. The 
word wrap always places its results in the #ctrl array. The word 
wrap's default action is to step through one line of text only 
and to store the format information found into the #ctrl array. 

The word wrap must always start from a location in the text where 
the format is known, for example, at the start of a line whose 
control/format information is known. The word wrap is supplied 
the information about this known line, its start address (found 
in the £wr field) and format information, to be held in the #ctrl 
array. When wrap finishes, the #ctrl array will contain a 
complete set of format information about the line which follows 
the line whose format information was passed to wrap in the #ctrl 
array. So, given information about a known line in the text, 
wrap will return control/format information about the following 
line in the text. These default actions of wrap were designed 
for stepping through the text, line by line, and producing 
control/ format information. 

The basic steps used by wrap are as follows: 

Use the information about the known line to quickly find 
the start address of the line which follows the known 
line. The line which follows is the line in which we 
are interested. 

Proceed forward from this new start position and look 
for text characters and format information. 

Each time a character is encountered, determine the 
width of the character and add it to a running total of 
the width of all characters on the current line. 

If format information is encountered, transfer it to the 
#ctrl array. 

If the total width ever exceeds the value of #wide , the 
end of the line has been found. The algorithm then 
moves back to the previous word break. The word before 
the last word break will become the last word on the 
line . 
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The word wrap looks in the system integer wraplim to decide when 
to stop wrapping through the text. Usually, wraplim contains a 
0, which means wrap should only wrap the current text line. If 
wraplim contains a non-zero value, it gives the address at or 
beyond which wrapping should stop. 

Before wrap overwrites the contents of the #ctrl with the newly 
found format information, it saves the analogous information for 
the previous half-line of text into the #pctrl array. 

1,3* 3.1 More on Intervals 

Keeping the control/format information the editor data structures 
updated requires constant use of wrap. The word wrap will obtain 
information about a desired line much more quickly if it is 
supplied a preceding line position with known format which is 
very close to the target line. This is why the interval concept 
was developed. The interval table holds control/format 
information about many places in the text (see the previous 
interval table diagram) . If the interval table is currently 
updated, one will never have to wrap more than one text interval 
in order to find information about any line of text contained in 
that interval. 

1.3. 3. 2 How the Interval Table Is Used 

When the editor starts, the entire text is word-wrapped to obtain 
control/format information about the first line of text in each 
text interval so that all of the entries in the interval table 
may be filled. 

During the use of the editor, the contents of each text interval 
will change and the format information in the corresponding 
control/format entry in the interval table will become invalid. 
Operations which invalidate information in the interval table use 
the word killivls to mark the invalid intervals. Since updating 
the entire interval table after each editing operation would be 
prohibitively slow, the interval table is left in an incomplete 
state. A background task, updates information on intervals which 
need to be updated. The word fixivl is called each time a 
keystroke is not available. This procedure will cause all 
intervals to be correct within two seconds, worst case. Only 
certain operations, such as leaping, require the entire interval 
table to be updated for proper functioning. 
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The interval table is used to expedite the process of finding 
formatting information for selected locations within the text. 

The word findchar fills the #ctrl array with the format 
information for a specific character in the text. The word 
findline fills the #ctrl array with format information for a 
specific line in the text. The words nextpage, prevpage t 
nextdoc, and prevdoc cause the #ctrl array to be filled with the 
format information for the page or document which is before or 
after a specified address in the text. All of these words use 
the interval table to get format information about a spot close 
to their desired destination quickly. Then, wrap word wraps from 
the location of known format to the desired location in the text. 

1.3. 3* 3* The Top Four Intervals 

Four interval table entries have special significance to the 
editor: 

#1 The first text interval 

#2 The interval which contains the start of the gap 

#3 The interval which contains the beot 

#4 The last text interval (?interval, which contains eot) 

It never changes, since the first line in the text cannot change 
(it always contains the starting document character) . Thus the 
state at the start of the text is always known. 

The gapivl system integer contains the address of the interval 
table entry corresponding to the text interval containing the 
start gap address. The beotivl system integer contains the 
address of the interval table entry corresponding to the text 
interval containing the beot address. These two intervals are 
complex intervals since they are separated by the gap and may or 
may not contain complete lines of text. The addresses of these 
interval table entries are saved for use by fixivl. If fixivl 
has problems fixing an interval table entry, and it notices the 
interval it is trying to fix is either gapivl or beotivl, it will 
skip over the interval and move on. 
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1.4 ROUTINES AFFECTING THE TEXT AND ITS POINTERS 



1.4.0 Text Maintenance Routines 



adjust ( al a2 n -> ) 

( pronounced ah- just ' ) 

Adjusts all text pointers which point within the range between 
address al and a 2 by the delta distance n. The pointers affected 
are: gap, bou, beot, bos, eos, savebos, extbos, bot, bor, eot, 

eor, oldop, oldpop, oldbos, oldeos, oldeos2, oldbos2, and 
oldpop2. Also uses realign to adjust the positions of the op and 
pop pointers and the contents of the window table . 

clearundo ( -> ) 

( pronounced cleer* un-doo ' ) 

Empties the undo buffer by setting bou pointer equal to the eou 
pointer. 

eou { - > a ) 

( pronounced ee * oh yu 1 ) 

Initials stand for end-of-undo buffer. Calculates and returns 
the address of the end of the undo buffer. 

realign ( al a2 n -> ) 

( pronounced ree * ah-line 1 ) 

Adjusts pointers and data structures which point into the range 
of text starting at address al and ending at address a2 by the 
offset n. The pointers affected by realign are op and pop. The 
word realign also affects all information in the window table 
entries . 

selsize ( -> n ) 

( pronounced sel ' size ) 

Forth word composed from English words "selection-size.” 
Calculates and returns the size in bytes n of the current 
selection. The equation gap bos - determines the selection size. 

1.4.1 Window Table Routine 

seenlines ( -> n ) 

f pronounced seen’ lines ) 

Returns the number n of half-lines visible on the display. 

1.4.2 Update Table Routines 

update! ( n -> ) 

{ pronounced up 'date store 1 ) 

Sets the update bit in the update array entry which corresponds 
to the specified screen line number n. 



20 - 




update? { n -> f ) 

{ pronounced up 'date kwes'chun ) 

Returns a true flag f if the update table entry corresponding to 
the specified line ?n in the window table indicates that the line 
requires updating. Also marks that line as no longer needing 
update . 



1.4.3 Interval Routines 

badivl { -> 0 | If no bad interval entry is found ) 

( -> a -1 | If a bad interval entry is found ) 
{ pronounced bad' iv'il ) 

This word stands for "bad interval." Searches through the 
interval table looking for the first bad (not updated) interval. 

If a bad interval is found, returns the text address which 
corresponds to the interval and a true flag. If no bad interval 
is found, returns a false flag only. 

fixivl ( -> ) 

( pronounced fix' iv'il ) 

Tries to fix one bad interval in the interval table. 

goodivl ( al -> a2 ) 

( pronounced gud' iv'il ) 

Returns the address a2 of the closest up-to-date interval table 
entry which precedes to the specified text address al . 

hideivls ( al a 2 -> ) 

( pronounced hide iv'ils ) 

Marks all invalid intervals corresponding to text located within 
the specified address range (between al and a2) as potentially 
valid by clearing the high bit on the #wr field. A potentially 
valid interval is an interval whose control/format array has only 
incorrect page and line number information. 

killivls ( al a2 -> ) 

( pronounced kill' iv'ils ) 

Marks all intervals corresponding to text located within the 
specified address range (between al and a 2) as invalid by setting 
%wr as equal to -1 in the corresponding control/format array. 

knownplace ( a -> ) 

( pronounced nown' plase ) 

Looks through the interval table to find the interval boundary 
closest to and prior to the desired text address a. Loads the 
control/format information which corresponds to the interval into 
the #ctrl array. 

lastknownline ( -> n ) 

( pronounced last' nown line 1 ) 

Returns the line number of the last displayable line of text 
entered by the user. 
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line>ivl 



( nl -> ) 

( pronounced line 1 to iv'il ) 

Looks through the interval table to find the interval boundary 
preceding the desired line number nl. Loads the control /format 
information corresponding to the interval into the #ctrl array. 

nearinterval ( al -> a2 ) 

( pronounced neer 1 in'ter-vul ) 

Returns the address a 2 of the nearest text location specified by 
the interval table which is closest to and prior to the address 
al . 

nearivl ( al -> a2 ) 

( pronounced neer’ iv’il ) 

Returns the address a 2 of the closest interval table entry which 
corresponds to the specified text address al. 

nextivl ( -> a -1 | If a valid interval is found. ) 

{ -> 0 | If a valid interval is not found. ) 

( pronounced nekst f iv'il ) 

Looks through the interval table to find the address a of the 
next valid interval table entry corresponding to an interval 
boundary address which is greater than the address found in the 
£wr field of the #ctrl array. If a valid interval is found, its 
interval table entry address and a true flag are returned. If no 
valid interval is found, a false flag is returned. 

partknown ( a -> ) 

( pronounced part 1 nown } 

Uses hideivls to mark all text intervals between the address a 
and the end of text, eot, as partially changed. 

previvl ( -> s -1 | If a valid interval is found ) 

( -> 0 | If a valid interval is not found ) 

( pronounced preev 1 iv’il ) 

Looks through the interval table to find the address a of a 
previous valid interval table entry which corresponds to an 
interval boundary address preceding the address found in the %wr 
field of the #ctrl array. If a valid interval is found, its 
interval table entry address and a true flag are returned. If no 
valid interval is found, a false flag is returned. 

putivl ( -> f } 

( pronounced put* iv’il ) 

Puts the control/format information found in the #ctrl array into 
corresponding interval table entry. The address in the %wr field 
finds the corresponding interval table entry. A true flag is 
returned if all interval table entries contain valid 
control/format information. 
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1.4.4 Wrap Routines 



prevwrap { -> ) 

{ pronounced preev’ rap ) 

Copies the contents of the previous control array, #pctrl, into 

the current control array, #ctrl. 

wrap ( - > ) 

( pronounced rap ’ ) 

Used to recalculate line, page, and document numbers. Performs 
one wrap of one half-line each time it is called unless a 
non-zero value is stored in wraplimit. Wraps the current line, 
that is, the line whose format information is stored in the 
current #ctrl array. If a non-zero value is stored in wraplimitt, 
it is assumed to be the address at which wrapping should stop. 

Since wrap may have to cross the gap, the skip characters 
(described in the "What’s in the Text" section should be properly 
positioned on either side of the gap (that is, preset should be 
called before using wrap), wrap does not affect the appearance 
of the display, it only affects the contents of the current 
line’s control/format array (#ctrl) . 

wrapthru ( a -> ) 

( pronounced rap ' thru ) 

Updates the interval table entries, starting with the entry 
nearest to the specified text address a, and ending at the line 
following the line containing a. Will fill in the interval table 
for all intermediate intervals in the range specified above. 



1.4.5 Routines Which Get Specific Control/Format Information 



findchar ( a -> ) 

( pronounced find' kair ) 

Fills in the #ctrl array with the control/format information for 
the beginning of the line on which the character residing at the 
specified address a is located. 

findline ( n -> } 

( pronounced find’ line ) 

Fills in the #ctrl array with the control/ format information for 
the specified line n. 

nextdoc ( a -> ) 

( pronounced nekst' dok ) 

Loads the #ctrl array with the control/format information 
corresponding to the first character in the document following a. 
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nextpage 



( a -> } 

{ pronounced nekst 1 page ) 

Loads the #ctrl array with the control/ format information 
corresponding to the first character in the page following a. 

prevdoc ( a -> ) 

( pronounced preev* dok ) 

Loads the #ctrl array with the control/ format information 
corresponding to the first character in the document preceding a. 

prevpage ( a -> } 

( pronounced preev* page ) 

Loads the #ctrl array with the control/format information 
corresponding to the first character in the page preceding a. 
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1.5 POINTERS AND DATA STRUCTURES SUMMARY 



1.5-0 Text Maintenance Integers 

beot ( pronounced bee 1 aht ) 

Beginning of second section of text 

bos { pronounced bahs ’ ) 

Beginning of selection 

bot { pronounced baht ' ) 

Beginning of user-entered text 

bou ( pronounced bee’ oh-yu ) 

Beginning of undo buffer 

endtext ( pronounced end T tekst ) 

Address of byte just past absolute end of text 

eos ( pronounced ee-oh-ess * ) 

Address beyond end of selection 

eot ( pronounced ee-oh-tee * ) 

Address beyond end of user-entered text 

eou ( pronounced ee-oh-yu 1 ) 

End of undo buffer. 

gap { pronounced gap * ) 

Address beyond first partition of text 

text ( pronounced tekst * ) 

Address of absolute start of text area 
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%lnl #ctrl + integer #lnl The local line number for this 

line within the current page 

£spr #ctrl + integer #spr Can hold one of four values: 

0, 1, 2 t or 3* Used by the 
words responsible for 
displaying lines of text 

0: Display 1 half-line 

1 : Do nothing 

2: Display 1 half-line 

3: Display 1 half-line 



1.5* 1*1 Paragraph Format Information Integers 



%lsp #ctrl + integer #lsp Local line spacing. Can hold 

one of three values: 2, 3. or 

4 . Used by the words 
responsible for displaying 
lines of text. 



2: Single-spaced text 

3: spaced text 

4: Double-spaced text 

%left #ctrl + integer #left Current left margin width, 

expressed in half spaces. 

0 <= n <= 158 

%wide #ctrl + integer #wide Width of the text area, 

expressed in half spaces. 

2 <= n <= 160 

^indent #ctrl + integer #indent Indent distance for this line, 

expressed in half spaces. 

0 <= n <= 158 
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£iwide #ctrl + 



integer #iwide 



Remaining width of the text on 
an indented line. 



%just #ctrl + integer #just Justification 



%tabs 



#ctrl + integer #tabs 



Left- justified 
Right- justif ied 
Center- justified 
Fully justified 



Two 80-bit bit arrays. The 
screen is 80 full spaces 
wide. The state of each bit 
in the first bit array 
indicates whether the 
corresponding space on the 
screen has a tab associated 
with it. The second bit array 
indicates whether the 
corresponding space has a 
decimal tab associated with it. 



1.5. 1-2 Document Format Information Integers 



%long 


#ctrl + 


integer 


#long 


The value in #long indicates 
how long a page can be before 
an implicit page break will 
occur. The page length is 
expressed in half-lines 


%above 


#ctrl + 


integer 


# above 


Holds the height of the top 
margin on a printed page, 
expressed in half-lines 


#below 


#ctrl + 


integer 


#below 


Holds the height of the bottom 
margin on a printed page, 
expressed in half-lines 


%lock 


#ctrl + 


integer 


#lock 


If this line is locked, will 
hold the ASCII value for the 
gray lock character 


pipage 


#ctrl + 


integer 


#ipage 


First page number in the 
document 


%iprint 


#ctrl + 


integer 


#iprint Number of the first printable 



page in the document 
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1.5.2 Control/Format Integer Array Offsets 



1.5. 2.0 Line Offsets 



£page 


00 


%pgl 


02 


%wr 


04 


%ln 


08 


%lnl 


0A 


%spr 


OC 


1.5. 2.1 


Format Offsets 


%lsp 


0E 


%left 


10 


%wide 


11 


^indent 


12 


%iwide 


13 


%just 


14 


%tabs 


16 


1.5. 2. 2 


Document Offsets 


%long 


2A 


%above 


2C 


%below 


2D 


%lock 


2E 


pipage 


30 


Jtiprint 


32 



1.5.3 Data Structures Integers 

#ctrl ( pronounced sharp* cee ' tee-ar-ell , or 

( sharp* kon- troll* ) 

Holds the address of the start of the #ctrl array 



#pctrl ( pronounced sharp* pee ' kon-troll ) 

Holds the address of an array which holds the previous contents 
of the #ctrl array 



#w table 

Holds the address 



( pronounced sharp* duh'bl-yu tay*bl ) 
of the start of the window table 



#update { pronounced sharp* up 'date ) 

Holds the address of the start of the update array 



#itbl { pronounced sharp' it'a-bl ) 

Holds the address of the start of the interval array 
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1.5.4 Window Table Integers 



Name 



Hex Value Description 



lastline $4E 

firstseen $10 
lastseen $3B 

middle 
eosline 
topline 

gapline 



Last line in window table. 

First window table line visible on screen. 
Last window table line visible on screen. 
Offset to the middle line in the display. 
Line in window table containing the eos. 
Global line number of the first line in the 
window table. 

eos line relative to window. 



1.5.5 Interval Table Integers 



Name 



Hex Value 



Description 



esize 

isize 

itblsize 

beotivl 



endtextivl 



gapivl 



$38 

$400 

esize isize * 



Size of a control/format array 
Size of the text interval represented 
by an interval table entry 
Size of the interval table 
Holds the number of the interval table 
entry corresponding to the text 
interval containing the beot address 
Holds the number of the interval table 
entry corresponding to the text 
interval containing the endtext address 
Holds the number of the interval table 
entry corresponding to the text 
interval containing the gap 



1.5.6 Wrapping Integers 



markpoint ( pronounced mark* point ) 

Place beyond which to seek pb/ds in wrap 



wraplim ( pronounced rap 1 lim ) 

Address of stopping point for wrap 



Jtpwrap ( pronounced per-sent' pee’ rap ) 

Previous array wrap address 

tfnextwr ( pronounced sharp' nekst’ duh'bl-yu ar 1 ) 

Holds the start address of the line which immediately follows the 
line whose control/format information is currently stored in the 
#ctrl array. This information is meaningful only following a 
loadline from window table. 



1.5.7 Unclaimed Integers 

pagebase { pronounced pa.je* base ) 

disktext ( pronounced disk' tekst } 

Start of text area on disk. 
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2. TEXT DISPLAY 



Introduction 



Text display is both a low-level and a high-level process. The 
low-level text display routines must convert encoded text data to 
displayable character strings. They must also work within the 
limitations of the screen and font sizes, and must actually draw 
the character data on the screen. The high-level text display 
routines must decide which regions of text are to be displayed 
and must be able to locate the formatting information for that 
region of text so that the lower-level display routines may be 
called upon to display the text. 
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2.0 A LOW-LEVEL LOOK AT TEXT DISPLAY 



The two lowest-level display words in the editor are build and 
disp. Both of these words are designed to display one line of 
text at a time, build prepares a line of text for display and 
disp draws the text on the screen. 



2.0.0 Preparing the Text for Display 

build converts one line of encoded text data into a displayable 
format, build always prepares the current line for display, that 
is, the line of text whose formatting information is currently 
stored in the #ctrl array, build analyzes the text data starting 
at the address found in the %wr field of the #ctrl array and 
stops at the address found in the #nextwr system integer. The 
#nextwr integer holds the address of the start of the line which 
follows the current line, build is probably the most complicated 
of the display words because it must understand how the format 
information found in the #ctrl array will affect the appearance 
of the text on the screen and must be able to describe the 
desired text appearance to a lower-level display routine, 'disp, 
which knows nothing about format codes . 

build's output is a character string (four bytes per character) 
which build stores in the line input buffer. The address of the 
line input buffer is kept in the lbuff ( el-buff ) system integer. 
Each character in the string is described with four bytes of 
information: 



byte 3 



byte 4 



byte 1 



byte 2 



Byte 1 

Extended ASCII value (8th bit is used) . Value can be in the range 
0 to CF. The Cat editor has only one text font, but it can 
display the font in two styles: normal and bold. The data which 

describes how each character looks on the screen is kept in a 
font table. Byte 1 of an lbuff character description contains a 
number which, when multiplied by 16, yields the offset into the 
font table. 

Byte 2 

Modifiers byte. Four bits in this byte are used to specify 
special character styles: bold, underlined, dotted-underlined , 

inverse-video . Another bit indicates that this character is the 
last character to be drawn. The bold bit in byte 2 indicates 
which font table -- normal or bold -- should be used. The 
settings of the other three style bits determine whether 
additional styling data should be applied to the main character 
data before it is drawn. The low-level drawing routine ~disp 
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will continue drawing characters on the screen until a modifiers 
byte with the stop bit in the modifiers byte set is encountered. 
This will be the last character drawn by ~disp on that line. 

Byte 3 

Currently unused 
Byte 4 

Overstrike character. This character, if any, will be OR'ed over 
the main character during display. Byte 4 provides a little more 
information on how the character should be drawn on the screen. 

If the character is an overstrike character its data will be 
merged into the screen display (with the use of an OR operation) 
rather than laid over the current screen contents. 



2.0.1 Special Text Preparation Cases 

As build creates its output string in the line buffer, it must 

look for and handle the following special cases: 

1. Page breaks or document separators in the text 

Page break and document break characters are single-byte 
characters in memory. But their screen representations fill 
the entire usable width of the screen. Therefore, when build 
encounters a page break or document separator character in 
the text it must construct the corresponding screen 
representation in character form in the Ibuff. The screen 
representation of a page break or document separator is 
composed of many small horizontal line characters, the page 
or document number character, and the special underline 
character which lies underneath the page or document number 
character. 

2. Margins, indents, tabs, and text justification 

build is responsible for (1) discerning the margin widths, 
indent widths, tab placements, and text justification styles 
that affect the line of text, and (2) inserting spaces and 
half-spaces as necessary to make the text meet the desired 
format specifications. 

3. Highlighted text 

build must check to see if the text being decoded lies within 
the current selection range. If it does, build must specify 
inverse video for the character being displayed, build must 
also handle the characters whose screen appearance is 
selection-dependent. For example, if a carriage return is 
selected, it is shown as a white arrow on a black background; 
if it is not selected it is represented by a white space. 
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4. Locked regions of text 

If the line to be displayed is part of a locked document, 
build is responsible for inserting the lock character (a 
vertical gray bar on both sides of the screen) into the front 
of the display string. 

5- Special character styles 

If any characters in the line have associated character 
styles, build must translate the editor style information to 
the disp-format style information. 



2.0.2 Editor Character Sets 



The following two diagrams, "The Cat Character Set," and "The Cat 
Display Character Set," show all characters which build can place 
in the lbuff and also shows the decimal and hexadecimal character 
codes which have been assigned to the characters. 

2. 0.2.0 Text Character Set 



Only the character codes for characters shown in the Cat text 
character set may appear in the text area. Of the characters 
shown in the Cat text character set, only those whose character 
codes range from $00 to $EF are actual typeable, displayable 
characters. The characters with codes in the $09 through $0D 
range are not usually visible but they can be entered from the 
keyboard. 

Note: A universe character, which is one level above the 

document character, was included to allow the implementation of 
universes , that is, sets of documents. The universe character 
is not currently supported. 

The character codes in the $E0 through $EF range are codes that 
can be allowed in the text but cannot be generated directly from 
the keyboard. 

The skip , paragraph format , calc , and locked calc characters are 
special characters which mark the start of a packet of non-text 
data within the text area. 

The characters corresponding to the character codes in the $E9 
through $EF range are modifier characters which indicate that the 
character which precedes them in the text has a special display 
attribute, that is, the character is underlined, bold, 
dotted-underlined, or has some combination of attributes. 
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The backspace attribute character (character code = $E8) may be 
used in the future to allow any character to be used as an accent 
for any other character. A backspace attribute character in the 
text would indicate that a backspace should be emitted before the 
character which precedes the backspace attribute is drawn on the 
screen, that is, the character which precedes the backspace 
attribute should be laid over the previous character in the 
display. 

The extend attribute is currently not used or understood. 
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2-.i "Cat" Character Set 
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2.0.2. 1 Display Character Set 

The display character set includes those characters that may 
appear in the text display area but whose character codes, in 
most cases, do not appear in the data area of the text. The 
character codes corresponding to the display characters lie in 
the $02 through $1F range. The characters in the display 
character set are shown in the diagram on the following page. 

Only the following four character codes are allowed to appear in 
the text as character data and in the line output buffer as 
character display data: tab ($09). document separator (SOB), 

page break (0C) , and carriage return (SOD). The significance of 
these four character codes depends on the environment in which 
they are found. When these characters are encountered in the 
text, they affect the appearance and organization of the text (a 
tab indicates a break in a line of text, a carriage return 
signifies the start of a new line, etc.). When these characters 
are encountered in the line output display buffer, they cause the 
visual representations of the characters to be drawn in the 
display (a return character code in the line output 'buffer causes 
the arrow graphic associated with a carriage return to appear on 
the screen) . The character codes for all other display 
characters will never be found in the text data. 

The display characters can be divided into four categories: 
display characters used to construct implicit/explicit page 
breaks lines and document separator lines, display characters 
used to represent in-line formatting characters (tab, carriage 
return, blanks), the display character used to represent locked 
documents, and the display characters used for screen diagnostic 
testing. 

Page breaks and document separators are composed of up to four 
types of display characters: 

1. Horizontal line segments that compose the main body of the 
page break or document character ($0E, SOB, $0C) 

2. Special smaller and slightly elevated numbers used for page 
numbering ( $ 10 — $ 19 ) 

3. Thin horizontal line segment that goes underneath the page 
number ($02, $03, $04) 

4. Horizontal line segment used to represent the selected 
version of an explicit page break 
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2 . .~ 2 - The Display Character Set 
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In-line formatting uses the following display characters: 

1. Selected tabs consist of two parts, the horizontal tab tail 
($08), and the tab arrowhead ($09). 

2. Selected carriage returns use an arrow display character 
which points downward and to the left (SOD). 

3- Margins, and deselected carriage returns use a mark blank 
character ($0A). 

4. Deselected tabs use the blank tabspace character (SIC). 

Locked documents are displayed with a series of document lock 
characters ($07) displayed along the edge of the locked 
document. The diagnostic routines use the special diagnostic 
display characters ($1E and S1F) for the screen test. 

2.0.3 Screen and Font Dimensions 

The Cat screen is 672 (decimal) pixels wide by 344 pixels high. 
Each character in the Cat's non-proportional font is 8 pixels 
wide. Therefore, 672/8 = 84 ($54) 8-bit wide characters can fit 
side-by-side on the Cat screen. Since a 2-character ( = 1 6 pixels) 
margin is always used on both sides of the text, a Cat display 
line supports 84 - (2 for left margin) - (2 for right margin) = 

80 columns of characters. 

Each character in the Cat character set fits within a 14-pixel by 
8-pixel rectangle. The Cat text display area, which holds 22 
lines of single-spaced text and has a 2-pixel high margin both 
above and below, is 22 x 14 = 308 + 2 + 2 = 312 pixels high. The 
ruler/status display area is 344 - 312 = 32 pixels high. 



2 pixels high 



22 lines, 

14 pixels per line, 
= 308 pixels high 



2 pixels high 



- top margin 



text display area 



bottom margin 



32 pixels high 



ruler/status area 



2 + 32 - 344 pixels 

38 - 



Total screen height = 2 + 308 



+ 




2.0.4 Drawing Text 

'disp, disp, and halfdisp are the three words that are ultimately 
responsible for redrawing the text portion of the display. The 
next section will discuss the routines which draw the ruler and 
status portions of the display, 'disp, a highly optimized 7 page 
assembly language routine, is the word which actually draws text 
on the screen, disp sets up the registers used to pass inputs to 
'disp. halfdisp is a short, optimized assembly routine used to 
draw blank half-lines. These routines have no knowledge of the 
encoded format used to store the text data. Therefore, the 
structure of the encoded text can change without affecting the 
display of the text. 

disp passes the following four pieces of information to 'disp 

1. the address of the normal font data table 

2. the address of the bold font data table 
3- the address of the line input buffer 

4. the address of the location in the display memory where the 
text should be drawn. 

The addresses of the first three parameters are fixed, disp uses 
the screen half-line number passed to it on the stack to 
calculate the location in screen memory where 'disp should start 
drawing. 

'disp traverses twice through the lbuff. During the first pass, 
'disp performs the following actions: 

1. Checks the bold bit in the modifiers byte of the lbuff 
character information. If the bit is set, it will use the 
bold font table; otherwise it will use the normal font table 
for step 2. 

2. Loads the character data for the top half of the character 
into the data registers. The desired character data is found 
by using the character code in byte 1 of the lbuff character 
information to form an offset into the font table. 

3. Checks the lbuff character information to see if an 
overstrike character is required. If it is, the data for the 
top half of the overstrike character is obtained, and AND’ed 
with the data in the data registers. 

4. Checks the inverse video bit. If it is set, the NOT 
operation complements the data in the data registers. 

5. Lays the data into screen memory. 
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During its second pass through the lbuff disp processes and draws 
the lower halves of the characters. “disp's actions during the 
second pass are very similar to those described above with one 
exception. During the second pass* after any overstrike 
character has been handled, “disp also checks the underlined and 
dotted underlined bits in the modifiers byte and modifies the 
character data accordingly before drawing it on the screen. 




2.1 A HIGH-LEVEL LOOK AT TEXT DISPLAY 



From a high-level point of view there are two steps required for 
text display: (1) the format information for the text to be 

displayed must be loaded into the window table, and (2) the lines 
represented by the entries in the window table must be displayed. 



2.1.0 Obtaining Display Information 

In order for any line or lines to be quickly chosen and 
displayed, all of the display routines expect control/ format 
information of text to be displayed to be stored in the window 
table. Therefore, before the actual display routines can be 
called, format information must be found and placed in the window 
table . 

loadline and storeline are words which can be used to access and 
change selected window table entries, loadline places the format 
information found in a specified window table entry in the #ctrl 
array, storeline stores the format information found in the 
#ctrl array into a specified window table entry. 

rewindow completely fills in the contents of the window table, 
rewindow is used when the display needs to be completely 
recalculated and redrawn, rewindow assumes that the system 
integer topline holds the global line number of the first line of 
text to be represented in the window table, rewindow finds the 
text address of the first character in the topline line and wraps 
from that address, using storeline to transfer format information 
from the #ctrl array to the window table, until each entry in the 
window table is filled up. rewindow also sets the update bit for 
each entry in the window table as it goes along: 

rewindow { -> ) 

{ Install skip markers on both sides of the gap. ) 

preset 

{ Load the #ctrl array with format information about the ) 

{ line which should appear at the top of the screen. ) 

topline findline 

( Wrap through the text enough times to fill in each entry ) 

( in the window table. Also update the interval table. ) 

lastline 1+ 0 
do 

( Store the information which is currently in the #ctrl ) 
( array into entry i in the window table. ) 

i storeline 
putivl drop 
wrap 

( Set the update bit for window table entry i. ) 

i update! 

loop ; 
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2.1.1 Drawing the Display 

refresh is the link between the low-level drawing routines build, 
disp, and halfdisp and the higher-level display routines. When 
called, refresh will check the update bits for all window table 
entries and will redraw, with the use of build, disp, and 
halfdisp, only those screen half-lines whose update bits are set. 

If a higher-level routine wants only selected lines on the screen 
redrawn, it will set the update bits which correspond to those 
selected lines before calling refresh. If a higher-level routine 
wants to completely redraw the screen it will use rewindow before 
calling refresh. The definition of refresh, which is fairly 
straightforward, is included on the following page. 



2.1.2 Line Spacing 

rewindow uses wrap to get control/format information about text 
to be displayed and storeline to store that control/format 
information into the proper entry in the window table, wrap was 
designed for this purpose since it pays attention to line spacing 
as it goes through the text. 

wrap will generate control/format information both for real lines 
of text and for display half-lines (if the text is 11 or 
double-spaced). Each time wrap is used, it decrements the 
contents of the %spr f ield of the #ctrl array by one. 

If the contents of the %spr are reduced to a negative number as a 
result of the operation (the %spr value will go from 0 to -1), 
wrap will reset the line spacing by replacing the contents of the 
%spr field with the value found in the £lsp field. If the result 
of the subtraction is a positive number, wrap will not finish 
wrapping the line. Instead, wrap will exit immediately after 
only having affected the contents of the £spr field. 

refresh differentiates between the window table entries which 
represent real text lines and those entries which represent 
display half-lines by checking the contents of the #spr field in 
the window table entry. If a 0 is in £spr, refresh will display 
a line. If a 1 is in %spr, refresh will do nothing. If a 2 or 3 
is in £spr, refresh will display a blank half-line. 

Each line of single-spaced text is represented by a pair of 
window table entries that are identical except for the contents 
of the %spr field. The first entry in the pair will have a 1 in 
its £spr field, refresh will do nothing when it encounters this 
entry. The second entry in the pair will have a 0 in its %spr 
field, refresh will draw a line of text when it encounters this 
second entry. 




: refresh { -> ) 

lastseen 1 + firstseen ( Index through all half-lines in the window table.) 
do ( Does this entry need to be redrawn? Exit if not.) i update? 
if 

( If it does need redrawing, place its format) 
i loadline { information in the #ctrl array.) 

( Check the line spacing state, should this line be drawn? 0 = real line 
of text , 1 = do nothing, 3 & 4 = draw blank half-line.) 

#spr c@ 

if ( If the first visible line, it must contain a blank half-line. ) 
firstseen i = 
if 0 halfdisp 

then ( If the #spr contains a number which is greater than one then this 
text is l£ or double-spaced. Insert blank half-lines.) 

#spr c@ 1 > 

if i 1+ firstseen - halfdisp 
then 
else 

( A printable full line of text cannot begin on the last half-line 
position ) 
lastseen i = 

if ( Draw the blank half line at the bottom of the screen.) 
i firstseen - halfdisp 

else ( Construct display output string for line and display text.) 
build i firstseen - disp 

then 
then 
then 
loop ; 
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2.3 Line Spacing 



Window Table 
Entries: 






%spr = 2 
%spr = 1 
%spr = 0 
%spr = 2 
%spr = 1 
%spr = 0 
%spr = 2 
%spr = 1 
%spr = 0 
%spr = 2 
%spr = 1 
%spr = 0 




3 

2 

1 

0 

3 

2 

1 

0 

3 

2 

1 
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In li -spaced text, each line of text is represented by three 
almost identical window table entries. The first of the three 
entries will have a "2" in its %spr field, the second will have a 

"1", and the third will have a "0" . 

In double-spaced text, each line of text is represented with 4 

window table entries. The first of the four entries has a ”3" in 

its %spr field, the second has a "2" , the third a "1" and the 
fourth a "0" . 



2.1.3 Drawing the Entire Display 

The goal of most of the high-level display routines is to get the 
current selection, as delimited by the bos and eos pointers, on 
the screen, new-display, eos-display, redisplay, and display are 
all display routines which share this goal, new-display and 
eos-display cause the entire screen to be redrawn, redisplay and 
display only resort to a complete redraw if they-absolutely 
must. If possible, redisplay and display will only redraw those 
screen half-lines which require updating. 

fit-display is the only high-level display routine which does not 
care about the current selection, fit-display's job is to 
display a specified region of text on the screen starting at a 
specified screen half-line number. Here is the stack notation 

for fit-display: 

: fit-display { halfline# start-text-rgn end-text-rgn -> ) 

The majority of fit-display’s work involves determining which 
line number should be displayed at the top of the screen. Once 
this number is determined, it is placed in the topline system 
integer and rewindow and refresh redraw the display. fit-display 
uses findchar to get format information about the two locations 
in the text and extracts the line numbers for the two characters 
from the format information. Once the start and end text range 
line numbers are known, fit-display can determine how many screen 
lines the text range encompasses and can position the text range 
accordingly . 

eos-display uses fit-display to display the current selection 
with the selection start line located at a specified screen 
half-line position: 

: eos-display ( halfline# -> ) 

bos eos prevchar fit-display ; 

new-display calls eos-display and requests that the current 
selection be displayed with the selection start located at the 
middle visible line on the screen: 

: new-display ( -> ) 

middle eos-display ; 
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2,1.4 Drawing Selected Portions of the Display 



display and redisplay try to redraw as few lines as possible, 
display checks to see if both the bos and eos are visible in the 
screen and, if they are, marks only the bos line for updating and 
uses refresh to redraw the line. If the bos and eos are not 
visible in the window, display calls upon new-display to 
completely redraw the screen: 

: display ( -> ) 
preset 

( Is the character before the eos visible? ) 
eos prevchar visible? 
if 

( Is the bos line represented in the window table? ) 
bos inwindow 
if 

( Set the update bit for the bos line. ) 
update! 

then \ 

( Redraw the bos line. ) 

else 

( Redisplay the entire screen. ) 
new-display 

then ; 



redisplay is designed to be used after a text change has been 
made at the gap (which is usually where the cursor or selection 
is found). The system integer gapline holds the number of the 
screen half-line which contains the gap (actually, the character 
which immediately precedes the gap), redisplay tries to redraw 
only those lines which could be affected by editing activity at 
the gap. The lines most likely to be affected by changes at the 
gap are the gapline and the line which precedes the gap line. 

Example: Take the case of a character being inserted at 

the end of a word which lies at the end of a wrapped line 
of text. The insertion could cause the word to be too 
large to still fit on its current line and it would have 
to be pushed down to the following line (the following 
line would then become the gapline) . This means that at 
least two lines would need to be redrawn: the new 

gapline (because a new word was inserted at its start) , 
and the previous line (because the last word was removed) . 
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If redisplay determines that the editing activity left the 
gapline in the window table, it will try to selectively fix the 
display. Otherwise, redisplay will call new-display to 
completely redraw the window. 

To selectively fix the display, redisplay compares the window 
table format information for the gapline, the line which precedes 
the gapline, and for the lines which follow the gapline, to the 
current format information returned by wrap in the #ctrl array. 

If the format information has changed, redisplay places the 
correct format information in the window table and sets the 
update bit for the line and uses refresh to redraw all changed 
lines. 



2.1.5 Scrolling the Display 

Two words -- scrolldown and scrollback -- scroll the text 
downward. Two other words — scrollup and scrollfwd -- move the 
displayed text upward. ( Downward means that text line 1 becomes 
2, 2 becomes 3» 3 becomes 4, and so forth; upward means the 
reverse) . 

Scrolling involves five steps: 

1. If the text is being scrolled, rather than unscrolled, 
the information required for undoing the scroll must 
be saved away. 

2. Check the selection position. If the selection is not on 
the top or bottom line of the display, it should be 
scrolled along with the text. If the selection is on the 
top line when the text is being scrolled up, or is on 
the bottom line when the text is being scrolled down, 

it should not scroll with the text but should stay 
pinned on either the top or bottom line. 

3. The contents of the screen, window and update tables must 
be shifted downwards or upwards in memory so that one 
line of visible text exits the screen in the appropriate 
direction . 

4. The lines which have been changed as a result of the 
scroll must be redrawn. 

5. The parameters which will allow the system to undo this 
scroll operation must be set up. 

scrollfwd and scrollback perform steps 1 and 3 above. If a 
scroll-undo operation is not occurring, they will save the 
selection/editor state operation into the special set of backup 
selection/editor state integers used only by the creeping and 
scrolling routines. 
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Next the selection position is checked. If the scroll operation 
would cause the selection to be scrolled out of the display, the 
selection will be collapsed and repositioned. If the screen 
contents are being scrolled up and the selection is on the top 
line of the display, the collapsed selection point will be moved 
to the first character on the following line (by altering the 
bos, eos, and gap pointers). If the screen contents are being 
scrolled down and the selection is on the bottom line of the 
display, the collapsed selection point will be moved to the first 
character on the preceding line (also by altering bos, eos, and 
gap pointers). If the selection is not in danger of being 
scrolled off the screen, it will simply be scrolled along with 
the line on which it resides. 

Scrolling only affects the top or bottom line on the screen. The 
screen image and data structures associated with the lines 
between the top and bottom lines are shifted, but not changed, 
scrolldown and scrollup (used to shift the screen, window table, 
and update table data in memory) take advantage of this 
characteristic of scrolling and use block moves to shift both the 
screen image and the corresponding window and update table entry 
data up or down in memory. After scrolldown or scrollup have 
finished, scrollfwd and scrollback must only get new information 
for, and display, the top or bottom line and the line which 
contains the cursor (the gapline). 

After scrolldown or scrollup has finished, the scroll operation 
is almost complete. Now, scrollback and scrollfwd will 
selectively redraw those screen lines that have been altered. If 
the screen contents have been scrolled down, new formatting 
information has been placed in the firstseen entry in the window 
table, scrollfwd will set the update bit which corresponds to 
the firstseen line so that it will be redrawn when the screen is 
refreshed. If the screen contents have been scrolled up, new 
formatting information has been placed in the lastseen entry in 
the window table, scrolldown will set the update bit for the 
lastseen line, scrollfwd and scrollback will also both set the 
new gapline line number and the update bit which corresponds to 
the gapline. 



- 48 - 




2.2 TEXT DISPLAY ROUTINES 



2.2.0 Low-level Text Display Routines 

build { -> ) 

{ pronounced bold' ) 

Scans through and converts the current line of text (text with 
embedded formatting, and other non-printable information) to a 
string of printable characters in a format suitable for use by 
'disp (ASCII-value byte followed by three bytes of additional 
information) . The string of printable characters is stored in 
the line output buffer lbuff. Any characters which lie within 
the current selection are marked as highlighted characters . 

Inserts the necessary spaces required for current justification. 

The bos (beginning of selection) and eos (end of selection) 
pointers should be properly set up prior to the use of build to 
ensure that any highlighted characters are properly encoded. 

build uses the address stored in the #wr field of the #ctrl 
field as the start address for its conversion process and uses 
the address found in the #nextwr integer (which should be the 
start address of the line which immediately follows the current 
line) as the end address. 

The word loadline, which transfers the contents of the 
control/format array for a specified line on the screen into the 
#ctrl array (that is, to make a line on the screen a "current" 
line), will set up the #nextwr integer contents. 

disp ( n -> ) 

( pronounced disp 1 ) 

Draws the line found in the line buffer, lbuff, on the screen at 
the half -line n. 

'disp ( code routine, parameter passed in registers ) 

( pronounced til* da disp * ) 

The word which actually puts data on the screen. Draws a single 
line of characters on the screen each time it is called. The 
characters to be drawn are located a buffer whose address is 
passed to "disp. Each character to be drawn is represented by 
four bytes of information. 'disp will continue taking characters 
from the buffer and drawing them until i reaches a character 
which has the end-of -buf fer bit set in its modifiers byte. Does 
not check to see if it is printing off the edge of the screen; 
this check is the responsibility of the caller. 

halfdisp ( n -> ) 

( pronounced haff 1 disp ) 

Draws a blank half-line on the screen at position n on the screen. 
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2.2.1 Mid-level Text Display Routines 



loadline ( n -> ) 

( pronounced lode* line ) 

Loads the control/ format information about the specified line n 
in the window table into the current control/ format array 
(#ctrl) . Also sets up the #nextwr integer so that it points to 
the start of the line which follows the current line (the line 
whose control/format information is stored in the #ctrl array) . 
build requires that the #nextwr is properly set up. 

refresh ( -> ) 

( pronounced ree’ fresh ) 

Steps through the update array and redraws any visible half-lines 
which have their update bits set. If the half-line has no text, 
halfdisp will be used. If the half-line contains text, build 
converts the formatted text to character text and disp places the 
characters on the screen in the correct line position. When 
refresh has finished redrawing selected portions of the screen it 
will clear all positions in the update array, refresh can only 
be used to redraw lines whose formatting information is already 
stored in the window table. 

rewindow ( -> ) 

( pronounced ree ' win ' doh ) 

Recompute the window array and mark all of lines for updating. 
Completely rebuilds the information in the window table. To 
reconstruct the window array rewindow makes the absolute line 
number found in the topline system integer the first line in the 
window array. Typically called after a situation where the 
entire display has been modified, for example, after an Explain 
message has completely overwritten the display. 

storeline ( n -> ) 

( pronounced stor' line ) 

Stores the current control/format information (found in the #ctrl 
array) into the window table field corresponding to the specified 
screen line number n. 



2.2.2 Utility Words Used by the High-Level Text Display Routines 

collapse ( -> ) 

( pronounced kah laps * ) 

Uses selected to set the update bits corresponding to all lines 
in the display which contain the current selection, then sets the 
bos to gap prevchar (which reduces the selection to one 
character) and uses refresh to redraw all lines which require 
redisplay. 
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differs? 



( n -> f ) 

( pronounced differs kwes'chun ) 

Returns a true flag if the control/format information which 
corresponds to screen line n in the window table is different 
than the control/format information in the #ctrl array. 

inwindow ( a -> n f | If flag returned is true. ) 

( a -> f | If the flag returned is false. } 

( pronounced in-win’ doh ) 

Returns a true flag if the character residing at the specified 
address a in the text belongs to one of the lines represented in 
the window table. If the flag returned is true, the screen line 
number which contains the character will also be returned. 

selected ( -> ) 

( pronounced se-lek 1 ted ) 

Sets the update bits which correspond to the lines in the window 
table which contain the current selection so that the next time 
the screen is redisplayed the selection will be displayed with 
proper highlighting. 

stepahead { nl -> n2 ) 

{ pronounced step’ a-hed ' ) 

Given the screen line number nl of a line in the window table, 
returns the screen line number n2 of the next line in the window 
table which contains text, stepahead skips over blank lines and 
,f do-nothing" lines. 

stepback ( nl -> n2 ) 

( pronounced step-bak ’ ) 

Given the screen line number nl of a line in the window table, 
returns the screen line number n2 of the first previous line in 
the window table which contains text, stepback skips over blank 
lines and "do-nothing" lines. 

visible? ( a -> f ) 

{ pronounced viz'a-bl kwes 1 chun ) 

Returns a true flag if the character residing at the specified 
address a in the text belongs to a line which is currently 
visible on the screen. 
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2.2.3 High-Level Text Display Routines 



bos-display ( n -> ) 

{ pronounced bahs 1 dis-play ’ ) 

Causes the beginning of the current selection to be displayed at 
the half -line number n on the screen. 

display ( -> } 

( pronounced dis-play 1 ) 

Completely redraws the display. If the format information about 
the selection range is already present in the window table, 
refresh redraws only those screen lines which require updating. 
If the lines which contain the selection range are not 
represented in the window table, new-display completely 
recalculates the window table and to completely redisplay the 
window contents . 

eos-display { n -> ) 

{ pronounced ee’ahs dis-play * ) 

Causes the end of the current selection to be displayed at the 
half -line n on the screen. 

fit-display ( -> } 

( pronounced fit 1 dis-play f ) 

new-display ( -> ) 

( pronounced noo' dis-play 1 ) 

Causes the end of the current selection to be displayed on the 
middle line in the display. 

redisplay ( -> ) 

( pronounced ree ' dis-play 1 ) 

redisplay is a less comprehensive version of display, redisplay 
should be used when a partial, rather than a complete display 
restoration, is required. redisplay will try to redraw only the 
section of the screen which has changed, but will redraw the 
entire display if necessary, redisplay wraps the text starting 
one line above the line which has changed, redisplay will 
continue wrapping and redrawing lines on the screen until it 
encounters a line which was not affected by the change, 
redisplay was designed for use after insertions and deletions at 
the gap have occurred (normal typing input is an example of an 
insertion at the gap) . 
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scrollback 



{ -> ) 

( pronounced skrole 1 bak ) 

Tries to scroll the lines on the screen down by one line. If 
there are previous lines to be displayed, scrollback will first 
collapse the selection if it is extended. 

Next, the cursor is repositioned to the start of the line 
which precedes the line which currently contains the cursor ( the 
#ctrl array is filled with information about the previous line 
and the bos is set to point to the address in the %wr field of 
the array) . scrolldown is then used to scroll the entire screen 
image down. 

Finally, the update bits which correspond to the top and 
bottom visible lines in the display are set and refresh 
redisplays them. The top line requires redisplay because it was 
just scrolled in. The bottom line could be left in a half 
visible state after the :roll operation. If this is the case, 
refresh will detect it and erase so that it will not be shown 

until it completely fits in the display. 

scrolldown ( n -> ) 

( pronounced skrole' down ) 

Used by the higher-level scrolling word scrollback to scroll 
those lines which do not require redisplay downward on the 
screen. Moves the screen bit image down by n lines and moves the 
entries in the window table down by n entries so that each entry 
still corresponds to the proper half-line on the screen. Fills 
the invalid entries at the top of the window table with new 
format information. 

scrollfwd ( -> ) 

{ pronounced skrole' for'wurd ) 

Tries to scroll the lines on the screen up by one line. If there 
are subsequent lines to be displayed, scrollup will first 
collapse the selection if it is extended. Next, the cursor is 
repositioned to the start of the line following the line which 
currently contains the cursor (the #ctrl array is filled with 
information about the following line and the bos is set to point 
to the address in the %vr field of the array), scrollup is then 
used to scroll the entire screen image up. 

Finally, the update bits which correspond to the top and 
bottom visible lines in the display are set and refresh 
redisplays them. The bottom line requires redisplay because it 
was just scrolled in. The top line could be left in a 
half-visible state after the scroll operation. If this is the 
case, refresh will detect it and erase so that it will not be 
shown until it completely fits in the display. 

scrollup ( n -> ) 

( pronounced skrole' up ) 

Used by the higher-level scrolling word scrollfwd to scroll those 
lines which do not require redisplay upward on the screen. Moves 
the screen bit image up by n lines and moves the entries in the 
window table up by n entries so that each entry still corresponds 
to the proper half-line on the screen. Fills the invalid entries 
at the bottom of the window table with new format information. 
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2.3 SUMMARY: INTEGERS USED FOR TEXT DISPLAY 



2.3.0 


Line Output 


Buffer Integers 


AO 


integer 


&horiz 


Number of horizontal 
half-spaces on a line. 


4 


integer 


Ibufwide 


Width of a character entry 
in the line buffer. 


lbuflen 




Length of Xbuff, build 
sets, print uses ) 


Ibufwidth 




The width at the last real 

char in lbuff 


bosptr 




Pointer into lbuff for 
bos 


eosptr 




Pointer into lbuff for 
eos 


2 . 3.1 


"disp" Integers 




0 


integer 


invbit 


Inverse video bit 


1 


integer 


boldbit 




2 


integer 


ulinebit 


Underline bit 


3 


integer 


dlinebit 


Dotted underline bit 


4 


integer 


stopbit 


When set, marks the end of the 
line output buffer contents 


7 


integer 


smallbit 




01 


integer 


$inv 


Mask used to check inverse video 
bit 


02 


integer 


$bold 


Mask used to check bold bit 


04 


integer 


$uln 


Mask used to check underline bit 


08 


integer 


$dln 


Mask used to check dotted 
underline bit 


10 


integer 


Send 


Mask used to check end-of-buf fer 
data bit 


80 


integer 


Shalf 


Mask used to check half-wide 
character bit 




2.3.2 Display-Only Characters 



Thin, horizontal bar which 
goes under a document number 



02 

03 

04 



07 


integer 


lok 


08 


integer 


tabO 


0A 


integer 


markbl 


0E 


integer 




OF 


integer 





10 

11 

12 

13 

14 

15 

16 

17 

18 



Thin, horizontal bar which 
goes under an explicit page 
number 

Thin, horizontal bar which 
goes under an implicit page 
number 

Gray, vertical, locked text 
character 

Flat, horizontal part of the 
tab arrow 

A white space character 

Horizontal component used to 
construct an implicit page 
line 

Horizontal component used to 
construct selected version 
of an explicit page line 

Special "0" used for page 
numbering 

Special "1" used for page 
numbering 

Special "2" used for page 
numbering 

Special "3" used for page 
numbering 

Special "4” used for page 
numbering 

Special ”5'’ used for page 
numbering 

Special "6" used for page 
numbering 

Special "7” used for page 
numbering 

Special "8" used for page 
numbering 
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19 



Special "9" used for page 
numbering 



1C 


integer 


tabspace 


Blank character which 
represents an unselected tab 
in the line output buffer 


IE 






Special "H" character used 
for diagnostic display 
testing 


IF 






Special ’’ # " character used 
for diagnostic display 
testing 


2.3.3 


Display and Text Characters 




09 


integer 


tabl 


Arrowhead part of the tab 
arrow 


OB 


integer 


ds 


Text: Document separator 

character 

Display: Horizontal 

component used to construct 
a document separation line 


OC 


integer 


pb 


Text: Page break character 

Display: Horizontal 

component used to construct 
an explicit page break line 


OD 


integer 


rtn 


Text: Carriage return 

character 

Display: Arrow used for 

display of selected carriage 
return character 


2.3.4 


Screen 


Size Integers 




50 


integer 


width 


Number of bytes in one 
display line 


54 


integer 


/scan 


Bytes in a scan line 


54 


integer 


/lscan 


Number of ’’visible" bytes in 
a scan line 


54 


integer 


active/scan 


Number of active bytes per 
line 


158 


integer 


height 


Scan lines per display 
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10 


integer 


bytes/char 


Bytes in a font table entry 


4 


integer 


logbytes/char 


Since we shift a lot 


0E 


integer 


scans/char 


Scan lines per character 


/scan 


integer 


scans/char* 




Bytes/line 




Bytes in a text line 


16 


integer 


lines/screen 


Lines on screen 


OE 


integer 


scans/ image 


Height of a character 


07 


integer 


tophalf 


Height/2 of a character 


10 


integer 


bytes/image 


Note: Code assumes this 

value ! 



- 57 - 




3. RULER/STATUS AREA DISPLAY 



Introduction 



The editor ruler/status area is divided into two parts: the 

ruler bar and the status line. The status line has four separate 



areas : 




1 . 


Line number icon 




2. 


Indicator lights 




3 . 


Mode icons (paragraph style, line spacing, 


keyboard I /II 


4 . 


Gas gauge 




The 


graphics used in the ruler/status area are 


comprised of 



characters from a special ruler font. The routines used to 
update and display the ruler/status area are discussed in this 
chapter. 
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3.0 THE RULER BAR 



The ruler bar is updated each time through the main editor loop. 
The word rule is responsible for updating the ruler bar. It 
performs three actions: 

1 . Decides what the ruler should look like by examining the 
current tab, margin, and indent settings, and sets up a 
temporary ruler buffer with information about the ruler 
appearance. The ruler buffer is similar in function to the 
line buffer used for text display. 

2. Uses "showrule to draw the ruler bar into a temporary bu.fer 

3. Uses "showstatus to display the status line on the screen 

The words checkgauge and checkline# are called each time through 
the main editor loop to update the gas gauge and line number if 
they have changed. 



3.0.0 The Ruler Buffer 

The ruler buffer is 84 decimal bytes long and is set up in the 
track buffer area during execution of rule. Each byte in the 
ruler buffer corresponds to one character position on the 
screen. The bits in each byte indicate which types of ruler 
items should be included in the ruler display area for each 
character position in the ruler buffer. The following types of 
items appear in the ruler: 

Left margin mark 
Right margin mark 
Indent mark 
Short tick mark 
Long tick mark 
Decimal tab mark 
Normal tab mark 

When rule sets up the ruler buffer it first marks the positions 
of all of the tick marks, then it marks the left /right margin and 
indent marks. Finally, it marks all of the tab stops. 



3.0.1 Displaying the Ruler Bar 

After the ruler buffer has been set up, rule uses the lower-level 
ruler display word 'showrule to draw the ruler into the temporary 
buffer. The display of the ruler requires three steps: 

1. The ruler buffer information is converted to character data 
which is laid in bit format into an off-screen buffer. 
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2. Checks the contents of the system integer blackruler. If 
blackmler is true, the ruler should be black. The ruler 
image is complemented. 

3. The bit-image of the ruler is transferred to the proper 
location in the screen memory. 

A 65 -byte lookup table named rulersmarts converts the byte 
information found in the ruler table to the ruler character code 
which should be displayed on the screen. 

There are characters in the ruler font for each possible 
combination of ruler marks which may co-exist in one character 
space on the ruler. For example, there can be a left margin 
mark, a tick mark, and a tab mark in one character position but 
there should never be a left and right margin mark in the same 
character position. 

Diagram 3*1 shows all the ruler font characters. 

“showrule steps through the ruler buffer converting byte codes 
into character codes (with the help of the lookup table) . The 
character code finds the data for the corresponding character in 
the ruler font. 

Once the data is found, it is drawn into an off-screen display 
buffer which is also located in the track buffer area during the 
execution of "showrule. 

“showrule also draws the lines which surround the ruler bar into 
the off-screen buffer. After the ruler has been drawn 
off-screen, the image is transferred to the proper location in 
screen memory to make it visible. 

Note: The ruler is drawn off-screen first because drawing it 

directly into screen memory produces too much flicker in the 
display. 

"showrule is very similar in function to ~disp, the routine used 
to draw text on the screen. The display of characters in the 
ruler font is more straightforward than the display of text 
because ruler font characters can have no accents or display 
attributes. Because of this a separate routine, "showrule, which 
is optimized for fast display, is used instead of the more 
general ~disp display routine. 
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3.1 THE STATUS LINE 



The status line contains information about the current line 
number in the text, the line spacing, justification style, and 
keyboard currently in use, and the amount of available memory. 

The status line is updated each time through the main editor 
loop. The word rule, described, uses the word "shows tatus to 
update the status line display. The characters in the ruler font 
used for the display of the status line are shown in Diagram 3 * 1 . 
page. 
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3.1 The Ruler Character Set 




^,1.0 Display of the Status Line 

The method used to display the status line is very similar to the 
method used to display text. In fact, the low-level screen 
display routine “disp draws the status line on the screen. The 
main difference between text display and status line display is 
that the character information for the status line is kept in a 
special buffer called the statbuff ( status-buffer ) . 



The information in the status buffer has the same format as the 
information in the line output buffer. Each character is 
described with four bytes of data (see the discussion of disp in 
the "Text Display" chapter. 

The status line character information is kept in a separate 
buffer so that its entire contents will not have to regenerated 
each time through the editor loop. The only data updated by 
"showstatus each time through the loop are the paragraph style, 
line spacing, and keyboard settings. The new values for these 
items is taken from the #ctrl array. The other status line 
information, the line number, gas gauge, and indicator lights, 
are only updated as necessary. 



3.1.1 Updating the Current Line Number 

The word checkline# updates the current line number in the status 
line. The line number is updated only if required. The system 
integer oldlnl holds the line number currently displayed in the 
status line, checkline# compares the local line number found in 
the #ctrl array to the oldlnl value and, if the line numbers are 
different, will directly update the line number information in 
the status buffer. 



3.1.2 Updating the Gas Gauge 

The gas gauge indicates how much memory is available. Free 
memory is defined as the space between gap and beot plus the 
space between here and applic. 

The word checkgauge updates the gas gauge setting. An update is 
done only when the change in text is significant enough to be 
visible on the gauge. The system integer oldgauge holds the free 
memory value used to generate the currently displayed gas gauge 
setting. If the gas gauge requires updating, checkgauge will see 
to it that the gas gauge information in the status buffer is 
altered. 

Note: The gas gauge supports two memory sizes, 256 K and 3&^K. 

The gas gauge gets longer when the system has 384k of RAM. The 
length (in pixels) to be used for the gas gauge is determined 
during initialization and is stored in the system integer 

gaugesize. 
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3.1.3 Updating the Low Battery Indicator 



The low battery user informs the use when his battery is about to 
die. An icon is displayed in indicator light 4, whenever the 
hardward lowbarrery indicator is turned on. 

checkbattery is called everytime through the main loop of the 
editor. 



3.1.3 The Indicator Lights 

The word indicate updates the indicator light data in the status 
buffer. The address of the string to be displayed in the light 
and the light position to be used is passed to indicate. There 
are five available indicator light display positions. A table 
called <stntuslights> , whose address is kept in the statuslights 
system integer, holds two pieces of information for each 
indicator light: the maximum string length (in characters) which 

may be displayed in the light, and the offset into the status 
buffer to the display information for the indication light. 

A complete list of light positions and the strings which may 
appear in the light positions follows: 



Light 0 


Light 1 


Light 2 


Light 3 


Light 4 


Phone 


LEARN? 


LOCAL 


PRINT 


(Low Battery Icon 


symbol 


LEARN 1 




DISK 






LEARN 2 




BACKUP 






(etc . ) 




CALC 





SORT 

SEND 

ADDSPELL 

SPELLCHECK 

DELSPELL 

FORTH 

DISK RECOVERY 

Light 0 is used by the Phone command. In the future, other 

strings relating to the Phone command may appear in Light 
1 (RINGING, BAUD300, etc.). 

Light 1 is used exclusively by the Learn command. Once a number 
has been assigned to a Learn sequence, the "?" changes to 
a number from 0 to 9* 

Light 2 indicates local leaping. 

Light 3 is called the "thinking" light. It is used by all 
commands which could have a slight response delay. 

"FORTH" appears in the thinking light when the Answer 
command is used and no query is pending. Two signs, 
TARGET and GETFORWARD, are used only during the editor 
development cycle. 
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The following shows a typical use of indicate: 



” Sort" 3 indicate rule 

” Sort” puts the address of the string to display on the stack 
3 specifies that light 3 should be used, indicate changes the 
light 3 display information in the status buffer. rule causes 
the ruler bar and status line to be redisplayed. 

Here is an example of how an indicator light is turned off : 

003 indicate rule 



3.1.5 The Low Battery Light 

The low-battery light is not a typical indicator light. It is 
triggered by a hardware test rather than by a user command. When 
the low battery light comes on, indicate will be used to display 
the image of a battery lying on its side. 
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3.2 INITIALIZING THE RULER/STATUS AREA 



The word initruler initializes the status line display. The 
system integer goldbytes holds the address of the data for the 
default status line display, initruler copies this default data 
into the status buffer. 




3.3 RULER DISPLAY/UPDATE ROUTINES 



rule ( code routine, passes parameters in registers ) 

( pronounced rool 1 ) 

Causes the ruler bar and status line to be redisplayed. Decides 
what the ruler bar should look like (based upon the current 
margin, indent, and tab settings) and creates an encoded 
description of the ruler bar in the status buffer. Uses 
'showrule to display the ruler bar and "showstatus to display the 
status line. 

'showrule ( code routine, passes parameters in registers ) 

( pronounced til 1 da sho 1 rool ) 

Displays the ruler bar. Takes byte information from the ruler 
buffer, converts it to ruler font character information, and draw 
an off-screen image of the ruler bar in the track buffer area. 

Then transfers the bit image directly to the screen. 
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3.4 STATUS LINE PI SPLAY/ UPDATE ROUTINES 



bl# ( nl -> n2 ) 

( pronounced bee *611 sharp 1 ) 

Does one step of converting a number to a character string, 
suppressing zeroes. If nl is non-zero, converts it to its 
corresponding ASCII value. If nl is zero, converts it to the 
ASCII value for a space. Used by checkline#. 

checkgauge ( -> ) 

{ pronounced chek 1 gaje ) 

Redraws the gas gauge if necessary. 

checkline# ( -> } 

( pronounced chek 1 line sharp ) 

If necessary, updates the line number in the status line and the 
contents of the oldlnl system integer. 

indicate ( a nl n2 -> ) 

( pronounced in 1 di-kate 1 ) 

Places the string located at address a of length nl into 
indicator light n2 and redisplays the status line. 

newgauge? { -> f ) 

( pronounced noo’gaje kwes 1 chun ) 

Checks to see if the gas gauge needs to be redrawn. If it does, 
newgauge? returns a true flag and updates the contents of the 
oldgauge system integer. 

'showstatus { code routine, parameters passed in registers ) 

{ pronounced til 'da sho 1 stay’tis ) 

Updates the paragraph style, line spacing, and keyboard 
information in the status buffer and then use^ ~disp to redisplay 
the status line. 

>status ( a nl n2 n3 -> ) 

( pronounced too 1 stay'tis ) 

Places the string of information located at address a, which is 
n2 bytes in length, into the status buffer starting at an offset 
of nl and uses n^ for the additional information required by disp. 
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3.5 RULER/STATUS AREA INITIALIZATION 



initruler ( -> ) 

( pronounced in-it' roo’ler } 

Initializes the oldgauge, oldlnl, and gaugesize system integers 
and copies the default status line data to the status buffer. 

>lbuff ( al a2 n -> ) 

( pronounced too ell’buf ) 

Moves the n bytes located starting at address al to memory 
starting at address a 2. Two bytes of zeros are appended to each 
two bytes of data transferred so that the final data is in the 
4-byte format required by disp. 
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3 . 6 SUMMARY 



3.6,0 Ruler/Status Area Data and Data Structures 

statbuff ( pronounced stat* buf ) 

Holds address of display buffer for status line. 

rulersmarts ( pronounced roo'ler smarts ) 

Holds address of look-up table for determining ruler display 
characters . 

statuslights ( pronounced stay'tis lites ) 

Holds address of status lights table. 

goldenbytes ( pronounced gohl'den bites ) 

Table of status line initialization data. 

goldbytes ( pronounced gohld 1 bites ) 

Holds address of status line initialization data. 

#goldenbytes ( pronounced sharp * gohl'den bites ) 

Holds length of status line initialization data. 

tfgoldenmodes { pronounced sharp 1 gohl 1 den modes' ) 

Holds length of mode initialization data. 



3.6.1 Offsets Into Status Buffer 



indichars ( pronounced in'di kares ' ) 

Holds offset to indicator data in the status buffer. 

modechars ( pronounced mode 1 kares ) 

Holds offset to mode icon data in status buffer. 

gaugepos { pronounced gaje 1 pahs ) 

Holds offset to gas gauge data in status buffer. 



3.6.2 Ruler/Status Screen Positioning Informatio n 

rulerstart ( pronounced roo'ler start ) 

Scan line at which ruler area starts. 

ruleredge ( pronounced roo'ler edj ) 

Left edge position for ruler/status area. 
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3*6.3 Ruler /Status Area Update Information 

oldlnl ( pronounced ohld 1 ell f en-ell f ) 

Holds current line number displayed in status line. 

oldgauge ( pronounced ohld* gaje ) 

Holds current gas gauge value displayed in status line. 

blackruler ( pronounced blak* roo'ler ) 

Holds flag used to indicate whether ruler area should be 
black-on-white or white-on-black 
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4 . THE CURSOR 



Introduction 



The cursor has two parts, a blinking cursor and a solid 
highlight . Each part serves a specific purpose. The cursor 
always shows where the next typed character will appear; the 
highlight always shows what will be removed when the Erase key is 
pressed. In a sense, the two parts are like the two ends of a 
pencil (one is for writing, the other for erasing) . 

The cursor may appear in five different states: 

1. Wide . The normal state when typing text; last typed 
characters appears in the highlight, blinking cursor 
indicates position where the next character will appear. 

2 . Narrow . Appears after leaping or creeping; cursor and 
highlight on same character, indicating that typing or 
erasing will take place at the location 

3. Extended. Appears when both Leap keys are pressed; highlight 
covers more than one character 

4. Split . Occurs when user leaps after extending highlight; the 
extended highlight remains where it is, the blinking cursor 
finds the new target, wherever it is in the text 

5 . Expanded -- occurs when the user extends the highlight (by 
pressing both Leap keys) during a leap; no blinking cursor in 
this state 

The cursor routines are used by almost all of the different 
editor commands. They allow the cursor to be positioned relative 
to displayed text. They also give information about the cursor 
(state, size of selection, location), and blink the cursor or 
cause it to disappear altogether (as when it is expanded). All 
of the cursor routines and their associated system integers are 
gathered here for easy reference. 
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4 . 0 CURSOR ROUTINES 



blink ( -> ) 

( pronounced blink ' ) 

If cursorblock holds a "0" , which means the cursor is allowed to 
blink, blink will cause the cursor to flash. If the cursor is 
currently on, if cursorstate holds a "-1", <cursoroff> will be 
used to hide the cursor. If the cursor is currently off, if 
cursorstate holds a "0" , <cursoron> will be used to show the 
cursor. The number of ticks until the next blink, either ontime 
(=$ 19 ), or offtime (=$ 19 ) is stored in the bticks system 
integer. If the text is clean (saved or just played back with no 
changes yet) , the ticks value is divided by four to speed up the 
cursor blink rate. 

cursorline ( -> n ) 

( pronounced kur'sir lyne ) 

Checks the character the cursor is currently over (uses the 
contents of the epos system integer) and the cursor state (checks 
the contents of the estate system integer) to determine which 
line the cursor is on relative to the current line. Returns the 
relative line offset between the current line and the line 
holding the cursor. If the cursor is split, it will always be on 
the current line and a line offset of 0 will be returned. If the 
cursor is narrow and on a page break preceded by a break, the 
cursor is on the previous line and a line offset of -1 is 
returned. If the cursor is wide and on a page break, then the 
cursor is on the next line and a 1 is returned. 

cursoroff ( -> ) 

( pronounced kur’sir off ) 

Forces the cursor off and leaves the cursor in a deactivated 
state. A false flag is placed in cursorblock to deactivate the 
cursor. If the cursor is currently on, <cursoroff> hides the 
cursor. 

<cursoroff> ( -> ) 

( pronounced brak'it kur'sir off ) 

Turns the cursor off. Puts a false flag in cursorstate to set 
the cursor state to off . Converts the pixel position of the 
cursor (held in the cx and cy system integers), to a position 
expressed in half-characters and half-lines. If cy = -1, this is 
a signal to not display the cursor. Restores image of character 
where blinking cursor was put. 

Next, checks rulerblink? to see if the ruler cursor was also 
being flashed. If it was, <cursoroff> removes the ruler cursor 
by filling the ruler cursor area in with the current ruler 
background color. 
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cursoron 



( -> ) 

( pronounced kur'sir ahn ) 

Forces the cursor on and leaves the cursor in an activated 
state. If the cursor is currently visible, if the cursor? 
integer holds a true flag, and the cursor is currently off, 
<cursoron> will be used to show the cursor and a false flag will 
be placed in cursorblock to activate the cursor. 

<cursoron> ( -> } 

( pronounced brak'it kur'sir ahn ) 

Turns cursor on. Puts a true flag in cursorstate to set cursor 
state to on. If cy = -1, this is a signal to not display the 
cursor. Converts the pixel position of the cursor, held in the 
cx and cy system integers, to a position expressed in 
half -characters and half-lines. 

Saves the bits which will be under the cursor in the 
cursorbuf memory buffer. Checks cwidth to see if the cursor is 
wide or narrow. Gets the proper cursor image either from 
ncursorimage ( narrow-cursor-image ) or wcursorimage 
( wide-cursor-image ) , masks out the areas of the cursor not needed 
(so that the character shows through the cursor) , and draws the 
cursor image on the screen. 

Next, checks rulerblink? to see if the ruler cursor should 
be flashed. If so, gets the height of the ruler cursor from 
hrulercursor and the current ruler color from blackruler (to 
determine the color for the ruler cursor) and draws the cursor in 
the ruler area. 

? expanded ( -> f ) 

( pronounced kwes'chun eks-pand'ed ) 

Checks the contents of the estate system integer. If estate 
holds a "3" » if the cursor is expanded, a true flag is returned. 

extend ( -> ) 

( pronounced eks- tend 1 ) 

Checks to see if the cursor is currently extended. If it is not, 
the selection is extended. First, extend checks to make sure the 
selection start and end points are in the right order. If the op 
is located before the beot the selection will be extended to the 
left. The bos is set equal to the op, the eos is already 
properly positioned. If the op is located after the beot the 
selection beginning and end points must be reversed. The eos is 

set to op nextehar, the op is set equal to the bos and the gap is 

adjusted in response to the new eos position. Now that the 
pointers are properly positioned, the text is redisplayed to show 
the extended cursor position, forceop is turned on so that the 
op will follow the next character typed. 

?extended ( -> f ) 

{ pronounced kwes'chun eks-tend'ed ) 

Checks the contents of the estate system integer. If estate 
holds a "2", if the cursor is extended, a true flag is returned. 
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extendedcursor ( -> ) 

( pronounced eks-tend'ed kur f sir ) 

Uses widecursor to make the cursor wide, and places a "2" in 
estate to specify an extended cursor. 

findnarrow ( -> ) 

( pronounced fynd 1 nair'roh ) 

Sets cx and cy for a narrow cursor. Uses cursorline to find the 
relative line position of the cursor. If a narrow cursor is not 
on the current line, then it must be on the end of the previous 
line. If the narrow cursor is on the previous line, stepback 
gets control/format information about the previous line. 

The value of cy expressed in half-lines is calculated by 
using inwindow to get the text line number in which the cursor is 
located, and then subtracting firstseen from the text line number 
to calculate the screen half-line number on which the cursor 
resides. If the cy position indicates that the cursor is visible 
in the window, loadline and build builds the character display 
version of the line in the line output buffer, and findwidth 
calculates the width of the entire line in order to set cx. 

The cursor width is set to the width of the last character 
in the line. If the narrow cursor is on the current line, or if 
the narrow cursor becomes positioned above the top of the window, 
findsplit sets cx and cy. 

findsplit { -> ) 

{ pronounced fynd 1 split ) 

Sets cx and cy for either a split cursor or for a narrow cursor 
positioned in the middle of a line or above the top of the window. 

Saves the screen line number which contains the cursor in 
cy. Checks to see if the cursor is on a page break character. 

If it is on a page break, the cursor cx is set so that the cursor 
is placed at the indent and ewidth is set to narrow. 

Otherwise, the cursor is on a normal character, findwidth 
finds the horizontal position at which the cursor should be 
placed and getwidth determines how wide the cursor must be to 
cover the character which it is over. 

findwide ( -> ) 

( pronounced fynd’ wyde ) 

Sets cx and cy for a wide cursor. If the entire wide cursor is 
located on the current line, inwindow finds the line number which 
contains the cursor, and then firstseen is subtracted from the 
screen line number to calculate cy expressed in half-lines. If 
the end of selection is not off the end of the line (?) the value 
in the eosptr finds the width of the character under the blinking 
portion of the cursor (ewidth) , and the x position of the cursor 
(cx) . If the end of selection is at the end of the line, the 
cursor width is always set to wide and cx is set to the width of 
the entire line. 

If the entire cursor is not on the current line, then it 
must be located at the start of the following line. If the 
following line is a page break, the cursor will be placed at the 
indent (cx = ^indent) and the cursor width will be set to wide 
(ewidth = 1). Otherwise, the cursor is positioned either at the 
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indent (if a valid character lies at the indent), or, if there is 
not a valid character at the indent, over the first valid 
character encountered. 

findwidth ( a -> n } 

( pronounced fynd* width ) 

Given the address of a character in the line output buffer, 
findwidth will calculate the widths of characters in the line 
output buffer up to and including the specified character and 
will return the result, expressed in half-character widths, on 
the parameter stack. 

fixcursor ( -> ) 

( pronounced fiks’ kur’sir ) 

Checks to see if the cursor has gone off the bottom of the 
display: cy seenlines 2- > . If it has, the screen is scrolled 
up until the line the cursor is on is at the bottom of the 
display and the screen display is refreshed. 

getwidth { a -> n ) 

( pronounced get* width ) 

Given a pointer a to a character in the line output buffer, 
returns the width of the character expressed in half-characters. 
The result can only be "1" (one half-character) or ”2" (two 
half-characters) . 

narrowcursor ( -> ) 

( pronounced nair * roh kur 1 sir ) 

Tries to force the cursor to a narrow state. If the cursor is 
located right after the start of a locked range of text, or if 
it’s on the first character in the local leap range, bor, it is 
not allowed to be made narrow, so widecursor makes it wide. 
Otherwise, estate is set to 0 to indicate a narrow cursor, epos 
is positioned at eos prevchar, and findnarrow sets the cursor's 
ex and cy position. 

narrowcursor? ( -> f ) 

( pronounced nair’ roh kur 'sir kwes ' chun ) 

Checks the contents of the estate system integer. If estate 
holds a "0", if the cursor is narrow, a true flag is returned. 

real? ( c -> f ) 

( pronounced reel' kwes ' chun ) 

Returns a true flag if the character "c" is a character which may 
appear in the text ($0B<=char<=$0D or $20<=char<=$DF) . 
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resetcursor 



( -> ) 

( pronounced ree'set kur'sir ) 

Repositions the cursor according to the cursor state. If estate 
is negative, splitcursor positions the split cursor. If estate 
is ”0'* narrowcursor positions the narrow cursor. If estate is 
"1" widecursor positions the wide cursor. If estate is "2", 
extendedcursor positions the extended cursor. 

?split ( -> f ) 

( pronounced kwes'chun split ) 

Checks the contents of the estate system integer. If estate 
holds a "-1", if the cursor is split, a true flag is returned. 

splitcursor ( -> ) 

( pronounced split' kur'sir ) 

Puts a "-1" in estate to indicate a split cursor and uses 
findsplit to set up ex and cy for the split cursor. 

widecursor ( -> ) 

( pronounced wyde' kur'sir ) 

Tries to force the cursor to a wide state. If the end of 
selection is located right at the end of a locked range of text 
or on the last character in a leap range eor, it is not allowed 
to be wide, so narrowcursor makes it narrow. Otherwise, estate 
is set to 1 to indicate a wide cursor, epos is positioned at eos 
prevchar, and findwide sets the cursor ex and cy position. 

widecursor? ( -> f ) 

( pronounced wyde' kur'sir kwes 1 chun ) 

Checks the contents of the estate system integer. If estate 
holds a ”1", meaning the cursor is wide, a true flag is returned. 
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4.1 " PLACE" PLACEMENT ROUTINES 



pushpos ( -> nl n2 n3 n4 n5 n6 ) 

(push-position) 

( pronounced push* pawz ) 

Push the contents of the key integers which define the editor's 
state onto the parameter stack. The integers pushed are: op, 
pop, bos, estate, eos, and gapline. 

savepos ( -> ) 

( pronounced save* pawz ) 

Saves the contents of the key editor state integers into a backup 
set of integers. The backup state integers are named: oldop, 
oldpop, oldbos, oldcstate, oldeos, and oldtopline, 

savepos2 ( -> ) 

( pronounced save* pawz too ) 

Saves the contents of the current editor state integers in a 
special set of backup state integers used only by the creep and 
scroll routines. The names of these special backup state 
integers are: oldop2, oldpop2, oldbos2, oldcstate2, oldeos2, and 
oldtopline2 . 

swappos ( -> ) 

( pronounced swop' pawz ) 

Returns the screen to the way it was before all operations other 
than a scroll or a creep. Swaps the contents of the backup 
editor state integers with the contents of the current editor 
state integers. 

swappos 2 ( -> ) 

{ pronounced swop* pawz too ) 

Returns the screen to the way it was before a scroll or a creep. 
Swaps the saved and current state variables for the editor. 
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4 . 2 CURSOR INTEGERS 



blinktime ( pronounced blink' tyme ) 

Holds the number of ticks until the next blink. 

bosptr ( pronounced boss' pee' tee arr ) 

Holds the offset into the line output buffer to the bos character 

epos ( pronounced see' pawz ) 

Holds the text address of the character over which the cursor is 
currently positioned 

cursor? ( pronounced kur'sir kwes ' chun ) 

Holds a flag that, if true, means the cursor is visible 

cursorblock ( pronounced kur'sir blok ) 

System integer controlling the blinking of the cursor. If 
cursorblock holds a true flag, the cursor will not blink. 

cursorbuf ( pronounced kur'sir buff ) 

System integer holding the address of the memory buffer used to 
hold the bit image of the screen contents currently under the 
cursor. 

cursorstate ( pronounced kur'sir stayt ' ) 

System integer which holds the flag which represents the current 
state of the cursor. A true flag means the cursor is on 
(blinking) and a false flag means the cursor is off (not 
blinking) . 

ewidth ( pronounced see' width ) 

Holds the current width of the cursor expressed as: #half-spaces 

- 1. A value of 0 means the cursor is one half-space wide and a 
value of 1 means the cursor two half-spaces wide (full-width). 

cx ( pronounced see' eks ) 

Holds the horizontal position of the cursor expressed in pixels 
cy ( pronounced see' whye ) 

Holds the vertical position of the cursor expressed in half-lines 

eosptr ( pronounced ee' oh ess pee' tee arr ) 

Holds the offset into the line output buffer to the eos 
character, placed by build if character was in last built line 

hrulercursor ( pronounced ayteh' roo'ler kur'sir ) 

Holds the height of the ruler cursor expressed in pixels 

ncursorimage ( pronounced enn' kur'sir im'ij ) 

Cursor image for narrow cursor 

off time ( pronounced off’ tyme ) 

How long to wait after turning cursor on (19 ticks) 
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ontime ( pronounced on 1 tyme ) 

How long to wait after turning cursor off (19 ticks) 



rulerblink? 

Holds a true 

wcursorimage 

Cursor image 



( pronounced roo'ler blink kwes ’ chun ) 
flag if the ruler cursor should be flashed 

( pronounced du f bl-yu kur'sir im'ij ) 
for wide cursor 
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4.3 CURSOR PLACEMENT INTEGERS 



4.3.0 Integers Which Hold the Current State of the Editor 

bos ( pronounced bee * oh ess ) 

Holds the address of the beginning of the selection (listed 
previously) 

estate ( pronounced see* stayt ) 

Holds the current state of the cursor: split (negative), narrow 

(0), wide (1), or extended (2), or expanded (3) 

eos ( pronounced ee’ oh ess ) 

Holds the address of the first character beyond the selection 
(listed previously) 

gapline ( pronounced gap* lyne ) 

Holds the number of the screen half-line in which the gap is 
located (actually, where the ’’gap 1-", or gap prevchar is located) 

op ( pronounced oh* pee ) 

Holds the address of the old cursor place 

p ( pronounced pee ' ) 

Means "place” 

po ( pronounced pee ' oh ) 

Means "pointer" 

pop ( pronounced pee ' oh pee ) 

Holds the address of the previous old cursor place 

4.3.1 Integers Which Hold the Previous State of the Editor 

These integers, which represent a snapshot of the text as it was 
when the last operation began, must be remembered in order to 
undo an operation. Except for the prefix old, they are the same 
as the integers defined on page. 

oldop 

oldpop 

oldbos 

oldcstate 

oldeos 

oldtopline 
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.2 Integers Which Hold the Previous State of the Editor 
Used by the Creeping and Scrolling Routines) 

oldop2 

oldpop2 

oldbos2 

oldcstate2 

oldeos2 

old topi ine2 
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5. WHAT’S IN THE TEXT 



Introduction 



This section explains what types of data are stored in the text and 
which editor Forth words may be used to locate and analyze the different 
types of data. The structure and locations of overstrike characters, 
character style bytes, paragraph format packets and document format 
packets are discussed. 
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5.0 STANDARD ASCII CHARACTERS AND BARE ACCENT CHARACTERS 



Characters in the Cat character set which may be typed (see 
following diagram) have character codes ranging from $09 to $C8 . 
In the editor, any byte data which has a value of $CF or less is 
assumed to be a byte of character data. 

The characters with codes from $00 to klastasc ( "last-ASCII" SAF) 
are considered to be a part of the extended ASCII character set. 
The characters with codes from $00 to &lastchr ("last-character," 
$BF) , which include all of the ASCII characters plus a few accent 
characters which may be typed individually (bare accents), 
represent all characters which may be individually typed and 
displayed on the keyboard. 



5.0.0 Break Characters 

A "break" character is any character that can cause a new 
paragraph to be formed in the text. Carriage returns, document 
separators, and page breaks are all classified as break 
characters are all classified as break characters. 

Four words find break characters in the text: firstbreak, 

lastbreak, nextbrk, and prevbrk. firstbreak and lastbreak search 

a specified text region and return either the address of the 
first or last break character in the region, nextbrk and prevbrk 
return the address of the break character which either follows or 
precedes the break character located at a specified address. 

There is also a word called break? which analyzes a character 
code input to determine whether or not the character code is a 
break character. 



5.0.1 Finding Character Data 

Because the text contains more than just character data, special 
words are included for moving from character data byte to 
character data byte in the text, prevchar takes the address of a 
character in the text and returns the address of the previous 
character in the text, nextchar takes the address of a character 
in the text and returns the address of the next character in the 
text. If prevchar or nextchar encounter a character with an 
overstrike in the text, they will always return the address of 
the overstruck character and never the address of the overstrike 
character (overstrike characters are not independent 
characters). Both of these words have the ability to recognize 
and skip over any non-character data they might encounter. 
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£■' "Cat" Character Set 

■ Shaded box = unused, reserved 
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5.1 OVERSTRIKE CHARACTERS 



The characters with codes from &firstacc ("first-accent,” SCO) to 
&lastacc ("last-accent," $CF) are special overstrike (or accent) 
characters which are treated specially both in the text and on 
the display. 

Overstrike characters are treated specially because, although 
they can be typed from the keyboard, they cannot be independently 
displayed on the screen; they must always be displayed with (on 
top of) another character. Overstrike characters do not exist 
independently in the text either, they are always associated with 
the character they accent. The character code for the overstruck 
character is combined with the character code for the overstrike 
character to form a 2-byte character code in the text (the 
overstrike character code always follows the overstruck character 
code). For example, the character u with an accent grave 
character over it, would be represented in the text with code for 
a "u" , $75. and the code for an $00, that is, $7500. 

Note: The double underline ($04) is a special exception to the 
above description of the treatment of overstrikes. The only 
character the double underline may combine with is the permanent 
space character ($93)* In fact, whenever a double underline is 
typed, it is automatically combined with the permanent space 
character. This means that the double underline will always 
appear to be one of the standard, typeable characters to the 
user. In the text, however, the double underline is really 
viewed as a permanent space character ($93) which is overstruck 
with a double underline accent character. 

The word accentable? will check a character code to determine 
whether the corresponding character is a character which may be 
accented (overstruck) . A carriage return is an example of a 
character which cannot be overstruck. Any character with a 
character code between and including $20 and $AF can accept an 
overstrike character. 

The word accent will take the address of a character in the text 
and, if the character has an overstrike character associated with 
it, will return the address of the overstrike character. 

Note: Many of the overstrike characters have normal character 

counterparts known as "bare accents". A bare accent character 
looks like an overstrike character but can be independently typed 
by the user and causes only a single-byte character code to be 
placed in the text. The character codes for bare accent 
characters start at $B0 and go up to $B8. 
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5.2 TEXT MARKER CHARACTERS 



The codes from &firstcmd ( first-command , $E0) to &lastcmd 
( last-command , $EF) correspond to text marker characters used to 
mark packets of character, paragraph, or calculation data in the 
text. The codes from &firsthid ("first-hidden," $F0) to SFF are 
all used to represent data in the text. 

Character Style Markers 

A Cat character can be displayed with up to four character 
styles: plain, bold, underlined, and dotted underlined. Any 

combination of these four styles may be used for any character. 

If a character has any style associated with it (other than 
plain) , it will be followed by a byte of style information in the 
text. For example, if you were to look at an underlined "a" in 
the text you would find a byte-$6l character code value for the 
"a" immediately followed by a $E9, which is the style byte value 
used for characters that are underlined only. 

The character style (attribute) markers have values in the range 
from $E9 to $EF. The bit lepresentations for the style marker 
values are listed below: 



Style 


Hex Value 


Binary 


■ Value 


Underline 


E9 


1110 


1001 


Bold 


EA 


1110 


1010 


Dotted Underline 


EC 


1110 


1100 


Underline+Bold 


EB 


1110 


1011 


Underline+Dotted 


ED 


1110 


1101 


Bold+Dotted 


EE 


1110 


1110 


Underline+Bold+Dotted 


EF 


1110 


1111 



The chart shows that bits #0, 1, and 2 are the real style bits in 
the style byte. Bit #0 (the leftmost bit) of the style byte is 
the underline bit, bit #1 is the bold bit, and bit 2 is the 
dotted underline bit. If a style bit is set (is a 1), the 
corresponding character will be displayed with that character 
style. 



5.2.1 Gap "Skip" Markers 

The gap area is a discontinuity in the text data. To let words 
which search through the text data know where the gap begins an: 1 
ends, special information is stored in the text area on both 
sides of the gap. The special information is 4 bytes in length 
and contains the following information: 




Beginning of gap: 



| skip character 


| offset to the end of 


the gap 


1 byte 
End of gap: 


3 bytes 




offset to the start of the gap 


skip character | 



3 bytes 1 byte 



Figure 5* 2 : Skip Information 

The skip character is a text marker character with a character 
code of $E0. The skip character either follows or precedes three 
bytes of offset information. Note that the order of the 
information is reversed on the different sides of the gap. The 
following memory dumps, executed from within the tForth 
environment, show how the skip information looks in memory: 

gap 10 dump 

43E804 E0 00 46 BD 69 70 20 2B 20 6F 66 66 73 65 74 0D . .F.ip + 
offset, ok 

beot 10 - 10 dump 

442F39 66 66 73 65 74 20 2B 20 73 6b 69 70 00 46 FA E0 offset + 

skip. F. . 

The beot can be computed from the three bytes following the skip 
marker at the gap using the following formula: 

gap + 4 + offset = beot 

The gap can be computed from the three bytes preceding the skip marke 
at the beot by the following formula: 

gap = beot - 1 - offset 

Where offset is defined as the number represented by the three 
bytes shown in Figure 5-2. 

When routines encounter a skip character while looking through 
the text data, they need to know how to get over to the other 
side of the gap. Two assembly language subroutines are available 
for this purpose: ~sk> ( skip-to-beot ) and ~sk< ( skip-to-gap ) . 

Both routines should be accessed with the 68000 JSR 
( jump-to-subroutine ) . Given the address of a skip character in 
the text, these routines will extract the offset from the skip 
information and will return the address of the other side of the 
gap. 
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5 .2.2 Paragraph Format Packets 



A paragraph is any sequence of non-break characters surrounded on 
both sides by break characters (described in 5-0.0). Paragraph 
format data describes the style (margins, tabs, indents, 
justification, and line spacing) in which the paragraph of text 
should be displayed. Paragraph format packets immediately 
following a carriage return, page break, or document separator 
affect the formats of all subsequent paragraphs until another 
format packet is encountered by the word wrap algorithm. 

A format packet contains data from the paragraph format 
information section of the control/format array in a simple 
encoded form. Each nibble ($x) of data in the paragraph format 
section is combined with a nibble with all bits set ($F) to form 
a byte of encoded format packet data ($Fx). The format packet 
data is marked in the text with a preceding paragraph format 
marker whose character code value is $E2. 

The character code values for the format marker character -- and 
for all bytes of data in the format packet -- are greater than 
the highest allowable value for character data, so that neither 
the format marker nor the packet data will be treated as 
character data. 



The following table illustrates the structure of a paragraph 
format packet: 



Byte 



Field Use 



0 

1-2 

3-4 

5-6 

7-8 

9-10 

11-13 

13-14 

15-16 

17-56 



$E2: paragraph format marker character 

Line space setting 

Unused 

Left margin setting 
Line width 
Indent setting 
Width of indented line 
Justification type { 0- 3 ) 

Unused 

Tab settings 



5.2.3 Manipulating Paragraph Format Packets 



brk+ ( pronounced bee 1 arr kay plus ) 

findpkt ( pronounced fynd' pak'it ) 

fpkt? ( pronounced eff' pak'it kwes'chun ) 

All of these words are used to find or identify format packets in 
the text. 



copypkt 

movepkt 

rotatepkts 

swappkt 



( pronounced kah'pee pak'it ) 

( pronounced moov' pak’it ) 

( pronounced roh’tayt pak'its ) 
( pronounced swop' pak’it ) 
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All of these words are used to move and insert format packets in 
the text. 



makepkt { pronounced mayk k * it ) 

Takes the paragraph formatting information from the #ctrl array, 
nibble-encodes the information, and places the new format packet 
at a specified location in the text, getpkt performs the 
converse action. It decodes the data in the format packet at a 
specified location in the text and places the information in the 
proper fields in the #ctrl array. 

pktbytes { pronounced pak’it byts ) 

Examines a region of the text and returns the total number of 
bytes of format data in the region. This is usually used to 
determine how large the undo buffer needs to be in order to hold 
packet information required for any future undo operation, 
savepkts and swappkts transfers format packets back and forth 
between the undo buffer and the text. 

samepkt? ( pronounced saym* pak'it kwes * chun ) 

Compares two format packets to determine if they are the same. 



5.2.4 Document Format Packets 

A document is any sequence of non-document characters which is 
surrounded on both sides by document separator characters. 
Document format data describes the printed and display appearance 
of the pages in the document (number of lines per page, number of 
blank lines above the top line on the page and below the bottom 
line on the page) and whether the document is alterable. 

Document format packets are located in the text immediately after 
the document separator character which marks the start of the 
document they affect. 

A document format packet contains data from the document format 
information section of the control/format array in a simple 
encoded form. Each nibble ($x) of data in the document format 
section is combined with a nibble with all bits set ($F) to form 
a byte of encoded document format packet data ($Fx). Every 
document separator character in the text is followed by a packet 
of document format data. 

The following table illustrates the structure of a document 
format packet: 
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Field Use 



Byte 

0 

1-2 

3-4 

5-6 

7 

8-10 

11-13 



SOB: document separator character 

Page length in half-lines 

Half-lines above first printed line on page 

Half-lines below last printed line on page 

Locked document byte 

Initial page in document 

First page number to print 



5.2.5 Manipulating Document Format Packets 
dpktbytes ( pronounced dee* pak’it byts ) 

Examines the text region between the start address al and the end 
address a2 and returns the total number of bytes n of document 
format information found in the region. This is usually used to 
determine how large the undo buffer needs to be in order to hold 
the document packet information required for any future undo 
operation, savedpkts and swapdpkts transfers document format 
packets back and forth between the undo buffer and the text. 



makedpkt ( pronounced mayk 1 dee’ pak'it ) 

Makes a new document format packet using the current document 
formatting information found in the #ctrl array and places it at 
a specified location in the text, getdpkt decodes a document 
format packet in the text and places the information in the 
relevant fields in the #ctrl array, getdocpkt is a special 
version of getdpkt which transfers document format information 
from the set up (user configuration) variables to the #ctrl array 

nextdsorcalc ( pronounced nekst dee* ess or kalk 1 ) 

This word, which means nex t-documen t- separ a tor-or- calc -marker „ 
locates document format packets in the text. 
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5.4 ROUTINES THAT INTERACT WITH SPECIAL DATA IN THE TEXT 



5.4.0 Handling Skip Data 

'sk> ( pronounced kair* it ess 1 kay gray* ter ) 

$a0: Address of skip character in the text. Given the address 

of the skip character which lies at the start of the gap region, 
'sk> will extract the offset to the other side of the gap from 
the skip information, add the offset to the gap start address, 
and return the address of the beot. 



~sk< ( pronounced kair* it ess 1 kay less 1 ) 

aO: Address of skip character in the text. Given the address of 

the skip character which lies at the end of the gap region, ~sk< 
will extract the offset to the start of the gap from the skip 
information, add the offset to the gap end address, and return 
the address of the start of the gap. 



5.4.1 Finding ASCII Data 



firstbreak ( al a2 -> a3 - or-0 ) 

{ pronounced furst* brayk ) 

Searches the text in the region which starts at address al and 
ends at address a2. Returns the address of the first break 
character encountered. Returns a "0" if no break is encountered. 

lastbreak ( al a 2 -> a3 - or-0 ) 

( pronounced last’ brayk ) 

Searches the text in the region which starts at the address al 
and ends at the address a 2. Returns the address of the last 
break character encountered. Returns a "0" if no break is 
encountered. 

nextbrk ( al -> a2-or-0 ) 

(next-break) 

( pronounced nekst f brayk ) 

Given the address of a location in the text, al, returns the 
address of the next successive break found in the text. A "0” 
will be returned if no successive break is found. 

nextchar ( al -> a2 ) 

( pronounced nekst* kair ) 

Returns the text address a 2 of the character which comes after 
the character at the address al. 

'nextchar ( Uses the AO and DO registers. ) 

( pronounced kair^t nekst* kair ) 

Lower-level subroutine used by nextchar. Returns the text 
address of the character which comes after the character whose 
address is in the AO register. 
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prevbrk ( al -> a2-or-0 ) 

( pronounced preev* brayk ) 

Given the address of a location in the text, al, returns the 
address of the first previous break found in the text. A "0" 
will be returned if no previous break is found. 

prevchar { al -> a2 ) 

{ pronounced preev f kair ) 

Returns the text address a 2 of the character which comes before 
the character at the address al. 

"prevchar ( Uses the AO and DO registers. ) 

( pronounced kair* it preev’ kair ) 

Lower-level subroutine used by prevchar. Returns the text 
address of the character which comes before the character whose 
address is in the AO register. 



5.4.2 Finding Data 



nextraatch ( n a -> a' ) 

( pronounced nekst* matsh ) 

Searches forward in the text, starting from address a, until the 
next occurrence of the byte value n is encountered. The address, 
a’ , which contains the first occurrence of the byte value is 
returned on the stack, nextmatch will skip over the gap if 
encountered. 

Warning: There are no boundaries on a nextmatch search. It will 

continue forever if the specified byte data value is not found. 

prevmatch { n a -> a’ ) 

{ pronounced preev 1 matsh ) 

Searches backwards in the text, starting from address a, until 
the first previous occurrence of the byte value n is 
encountered. The address a' which contains the first previous 
occurrence of the byte value is returned on the stack, prevmatch 
will skip over the gap if encountered. 

Warning: There are no boundaries on a prevmatch search. It will 

continue forever if the specified byte data value is not found. 



5.4.3 Analyzing ASCII Data 



accent ( a -> a'-or-O ) 

( pronounced ak 1 sent ) 

Given the address a of a character in the text, returns either 
the address a’ of the accent character associated with the 
original character, or "0” if the original character does not 
have an accent. 
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accen table? 



( c -> f ) 

{ pronounced ak-sent 1 -a-bul ) 

Returns a true flag if the character code c is able to receive an 
accent ($20<= character code <=$AF). 

break? ( c -> f ) 

( pronounced brayk 1 kwes ' chun ) 

Returns a true flag if the character c is a character which would 
cause a new paragraph (a document separator, page break, or 
carriage return) . 

page? ( c -> f ) 

( pronounced pay j kwes 1 chun ) 

Returns a true flag if the character c is a page break character. 



5.4.4 Handling Attribute Data 



attribable? ( c -> f ) 

{ pronounced at-trib'a-bl kwes 1 chun } 

Returns a true flag if the character c can have an attribute 
(underlined, boldfaced, etc.). Characters with character codes 
in the range S20<=code<=$AF can accept attribute data. 

attribute ( a -> n-or-0 ) 

( pronounced at 1 tri-bute ) 

Given the address a of a character in the text, returns either 
the attribute byte n for the character, or, if 0 if the character 
does not have an attribute associated with it. 

bare? { c -> f ) 

{ pronounced bair* 1 ~es ' chun ) 

Returns a true flag if the character c is a bare accent character. 



5.4.5 Getting Information About Format Packets 



brk+ ( al -> a2 ) 

( pronounced brayk' plus ) 

Given al, the address of a break character, returns a2, the first 
byte beyond the break character where a format packet may be 
f ound . 

~dfmt ( pronounced kair'it dee for'mat ) 

aO: Address in text where a document format packet is located. 
Decodes a document format packet in the text and places the 
format information in the #ctrl array. 
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dpktbytes { al a2 -> n ) 

{ pronounced dee’ pak'it byts ) 

Examines the text region between the start address al_ and the end 
address a2 and returns the total number of bytes n of document 
format information found in the region. This is usually used to 
determine how large the undo buffer needs to be in order to hold 
the document packet information required for any future undo 
operation, savedpkts and swapdpkts transfers document format 
packets back and forth between the undo buffer and the text. 

findpkt ( al a2 -> a3 ) 

{ pronounced fynd' pak'it ) 

Searches the text range starting at address al and ending at 
address a2 and returns the address eQ of the first paragraph 
format packet found. If no packet is found, a^ will be 0. 

~fmt> ( pronounced kair'it for'mat gray'ter ) 

aO : Address in text where format packet is located. Decodes a 
format packet in the text and places the format information in 
the #ctrl array. Leaves aO pointing just beyond the packet. 

fpkt? ( a -> f ) 

{ pronounced eff 1 pak'it kwes'chun ) 

Returns a true flag if a paragraph format packet follows the 
break character located at the address a. 

getdocpkt ( -> ) 

( pronounced get* dank* pak'it ) 

Transfers document format information from the Setup array to the 

#ctrl array. 

getdpkt ( a -> ) 

( pronounced get* dee* pak'it ) 

Loads the information from the document format packet located at 
address a in the text into the #ctrl array. 

getpkt { a -> ) 

( pronounced get 1 pak'it ) 

Decodes the format packet located at address a in the text and 
places the format information in the #ctrl array. 

nextdsorcalc ( al a2 -> a3 ) 

( pronounced nekst' dee-ess' or kalk' ) 

Looks through the text region starting at address al and ending 
at address a2. Returns the address of the first document 
separator or Calc marker encountered, if any. If no document 
separator or Calc marker is found, return the end address of the 
region . 

pktbytes ( al a2 -> n } 

{ pronounced pak'it byts ) 

Examines the text region starting at address al and ending at 
address a 2 and returns the total number of bytes n of format 
information found in the region. 
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samepkt? ( al a2 -> f ) 

( pronounced saym* pak'it kwes'chun ) 

Compares the paragraph format packets located at addresses al and 
a 2 in the text and returns a true flag if they are the same. 



5.4.6 Moving format Packets Around 



copypkt ( al a2 -> ) 

( pronounced kah'pee pak’it ) 

Copies the contents of the first paragraph format packet found on 
or after the text source address al over the contents of the 
first paragraph format packet found on or after the text 
destination address a 2. 

makedpkt { a -> ) 

{ pronounced mayk dee * pak 1 it ) 

Encodes the document format information found in the #ctrl array 
and places the resulting document format packet at the specified 
address a in the text. 

makepkt ( a -> ) 

(make -packet) 

{ pronounced mayk pak* it ) 

Encodes the format information found in the #ctrl array and 
places the resulting encoded format packet at the specified 
address a in the text. 

makespace ( a n -> a' ) 

( pronounced mayk’ spays ) 

Tries to create a hole in the text at address a of size n bytes. 
If there is not enough room, an error message is issued. If 
there is enough room, makespace moves the text around, adjusts 
the text pointers, and returns the address where the desired 
space is located (the initial address could have been altered due 
to text movement). 

maxundo ( - > n ) 

( pronounced maks' un’doo ) 

Returns the maximum capacity of the undo buffer expressed in 
bytes . 

movepkt ( al a2 -> ) 

( pronounced moov’ pak’it ) 

Creates a paragraph format size opening in the text at the 
destination address a 2 and moves the paragraph format packet 
located in the text at address al into the opening. 

rotatepkts ( al a2 a3 -> ) 

( pronounced roh'tayt pak* its ) 

Rotates the contents of the three paragraph format packets 
located in the text at addresses al (=packet 1), a 2 (=packet 2), 
and a^ (=packet 3)- The rotation order is: packet 1 > packet 2 

, packet 2 > packet 3» packet 3 > packet 1. 
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savedpkts ( -> ) 

( pronounced sayv ! dee'pak'its ) 

Move all document format packets located between the address 
found in the system integer prepkt and the start of the gap into 
the undo buffer. 

savepkts ( -> ) 

( pronounced sayv 1 pak'its ) 

Move all format packets located between the address found in the 
system integer prepkt and the start of the gap into the undo 
buffer. 

swapdpkts ( -> ) 

( pronounced swop' dee 1 pak'its ) 

Swap all document format packets located in the text between the 
address found in the system integer prepkt and the start of the 
gap with the document packets in the undo buffer. 

swappkt { al a2 -> } 

( pronounced swop' pak'it ) 

Checks to see if there are paragraph format packets at the text 
addresses al and a 2. If there are paragraph format packets at 
both locations, swaps the contents of the packets. If there is 
only a paragraph format packet at one of the locations, inserts a 
copy of the packet which does exist into the text at the location 
which did not contain a format packet. 

<swappkt> ( al a2 -> ) 

{ pronounced brak'it swop' pak'it ) 

Swaps the contents of the paragraph format packet lying after the 
break located at address al with the contents of the paragraph 
format packet lying after the break located at address a 2. 

swappkts { -> ) 

{ pronounced swop' pak’its ) 

Swap all format packets located between the address found in the 
system integer prepkt and the start of the gap with the 
corresponding format packets in the undo buffer. 
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5.5 SUMMARY 



5.5-0 Break Characters 



SOB 


integer 


ds 


Document separator character code. 




$0C 


integer 


pb 


Explicit page break character code 


• 


SOD 


integer 


rtn 


Return 


character code 




5 . 5 .I 


Text Markers 








SEO 


integer 


&skip 




Skip the gap 




SE2 


integer 


Lfmt 




Format packet code 




$e4 


integer 


&calc 




Calculation packet code 




SE5 


integer 


&lockedcalc 


Locked calculation packet 


code 


SE8 


integer 


&attr 




Character attribute code, 
in arithmetic code words 


Used 


SEC 


integer 


&dln 




Dotted underline code used 
arithmetic code words 


in 



5.5.2 Character Code Limit Values 



SAF 


integer 


&lastasc 


SBF 


integer 


klastchr 


SCO 


integer 


kfirstacc 


SCF 


integer 


&lastacc 


SEO 


integer 


&firstcmd 


SEF 


integer 


&lastcmd 


SFO 


integer 


&firs thid 




Format 


Packet Values 



$39 integer pktsize 

Size of a paragraph format packet in the text, including format 
character 

$0E integer dpktsize 

Size of a document format packet in the text, including document 
separator character 
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6. INSERTING, ERASING, AND COPYING TEXT 



Introduction 



Inserting (typing), erasing, and copying are the three most basic 
Cat editing operations. The inserting routines must decide what 
styles, if any, should be given to new characters being entered 
into the text. The insert routines will gather characters in the 
gap area until they get a chance to insert the block of 
characters into the text. The copy routines copy the current 
select on and insert the copied characters into the text. The 
copying process is very similar to the text insertion part of the 
typing process. The erase routines will either erase forward, or 
backward or will erase an extended selection from the text 
depending upon the cursor state when Erase is used. 
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6.0 INSERTING TEXT 



Characters typed at the Cat keyboard do not go directly to the 
editor. The interrupt routine responsible for scanning the 
keyboard array places key/character information in a low-level 
key event queue each time a key or keys is detected going up or 
down. When the editor is ready to receive characters it uses 
Forth keyboard I/O words to obtain key/character data from the 
queue. The Cat keyboard interface and the Forth words used to 
handle keyboard input are discussed in Chapter 13. 

Insert (with a capital "I”) is the editor word which takes typed 
character input and implaces it in the text. The three main 
functions of Insert — gathering characters, inserting characters 
into the text, and redisplaying the text -- are discussed below. 



6.0.0 Checking the Attribute State 

Before Insert actually places characters in text, it must be 
determine whether special character modifiers are needed. If 
there are any attributes common to the nearest printing 
characters on both sides of the insertion point, all inserted 
characters will inherit those attributes. Printing characters 
include all characters excepting break characters and tabs. If 
any such attribute is on only one side of the insertion point, 
the inserted material will not inherit that attribute. 

The attributes associated with the characters on both sides of 
the insertion point are AND'ed together to obtain the attribute 
value for the new character. The result of ANDing together two 
completely different attribute values -- bold and underline, for 
example -- is 0 or $E8. If Insert finds either of these results, 
the new character will not be assigned an attribute. If the 
resulting value is other than 0 or $E8, it will be used as the 
attribute value for the new character. 

As an example, imagine that the cursor is wide and a new 
character is to be inserted between an underlined character and 
an underlined, boldface character. When the underline attribute 
value, $E9, and the underlined-bold attribute value, $EB are 
AND’ed together, the resulting value is SE9, the underlined 
attribute value. Since this value is not 0 or $E8, the new 
character, and all subsequent characters placed between the 
original attribute-determining characters, will be given the 
underline attribute. 

The following code excerpt from Insert shows the attribute 
assignment decision process: 
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beot narrowcursor? ( look for attributes beginning at insertion point ) 

if prevchar then dup { if cursor is narrow, step back one character ) 

begin dup c@ pb rtn ( skipping all break characters ) 

inrange while nextchar again ( forward to printable character ) 

attribute swap ( find attribute here and swap for insertion point again ) 

begin prevchar dup c@ pb rtn ( skip all break characters ) 

inrange 0= until ( scan backwards for first printable character ) 

attribute and ( find attribute here, then AND with other attribute ) 

dup e8 = { if no common attribute bits ) 

if drop 0 then attrib to ( mark for ”no attribute” ) 



6.0.1 Gathering Characters 

Insert uses continueinsert? (which uses the lower-level Forth 
word <?k>) to obtain characters from the keyboard event queue. 

Insert will not terminate execution until the event queue is 
completely empty. This ensures that all input characters will 
enter text as quickly as the previously entered characters can be 
displayed. As the characters are received (and assigned 
attributes if necessary), they are placed temporarily in the gap, 
immediately after the skip information. A local variable pointer 
named ”place” keeps track of the offset into the gap to the 
position where the next received character should be placed. 

Before each character is placed in the gap area, Insert uses the 
word enoughtext to check the amount of available gap space. 

There must be at least enough room for current temporary 
insertion string and for a document format packet (in case the 
next character received is a document separator character) for 
Insert to proceed: 

place gap - ( length of the current insertion string ) 

dpktsize + ( the most gap space which could be ) 

( required by the next character ) 
enoughtext not ( if there is not enough text, error ) 

if 

2drop 

noerror error 
leave 

then 
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If there is enough room, Insert will analyse the character just 
received to determine how to handle it. There are six possible 
types of characters Insert will have to handle: 

1. Accented characters (two bytes) 

2. Accented character with an attribute (three bytes) 

3- Document separator characters (dpktsize +1 bytes) 

4. Normal character preceded by a bare accent character (two 
bytes) 

5 . Normal character with attribute (two bytes) 

6. Normal character (one byte) 

Accented characters are easy to recognize because their character 
value is greater than $FF, the maximum value which may be 
expressed with 1 byte. When an accented (2-byte) character is 
encountered, it is stored (using w! ) at the location currently 
pointed to by the place pointer. If the accented character is to 
receive an attribute, the accent part of the accent character is 
bumped over by one byte and the attribute value is inserted 
between the main character and its accent character. 

Whenever a document separator character is encountered, a 
document format packet must be created and inserted, makedpkt 
constructs a document format packet in the gap using the document 
formatting information currently found in the #ctrl array. A 
page break character is also inserted in the temporary gap string 
immediately after the document format packet. 

If the character was not an accented character or document 
separator character, it must be a normal character represented by 
as a single byte. It is inserted, using c!, in the gap at the 
location pointed to by place. If the normal character is a 
character that can receive an accent and if the character which 
precedes the normal character in the gap is a bare accent 
character, the normal character and the bare accent character 
will be swapped and changed into a standard, accented (2-byte) 
character: 



swap c@ accentable? ( 
place prevchar c@ bare? ( 
and ( 
if 



place prevchar dup ( 



c§ ( 

place c@ ( 

rot c! ( 

( 

OF and CO or ( 

place c! ( 

( 

else 



Can this character receive an accent? ) 

Is previous character a bare accent? ) 

If both of these cases is true. . . ) 

Duplicate address of bare accent. ) 

Fetch the bare accent. ) 

Fetch the character to be accented. ) 
Store the character to be accented in ) 
the location where the bare accent was. ) 
Turn bare accent into a normal accent. ) 
Store it immediately after the main ) 
character. ) 
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If the normal character is not turned into an accent character, 
Insert will check to see if the character should receive an 
attribute. If the character can and should receive an attribute, 
the attribute value will be stored in the gap area immediately 
behind the character. If the character does not receive an 
attribute, Insert's character handling process is completed. The 
place pointer will be properly incremented and continueinsert? 
will be used to check for the availability of more characters. 

continueinsert? will return a true flag and a character code if a 
valid insertable character is available. If no valid character 
is available, a false flag will be returned, and the Insert 
character handling loop will be terminated, and the process of 
inserting the temporary character string into the text will be 
started. 



6.0.2 Inserting Characters Into the Text 



The word insertblock inserts the characters in the gap into the 
text. Before inserting the string into the text, insertblock 
checks for the following cases: 

Locked text 
Empty text 

Not enough room for insertion string 
Extended selection 

If the text is locked, or if there is not enough room for the 
insertion, an error message is issued and no text is inserted. 

If the text is empty, the editor is initialized using initedde 
before the insertion. If the cursor is extended, it will be 
collapsed before the insertion. 

If the string is to be inserted, it will be placed either before 
or after the bos character. Since any extended selections were 
collapsed, the bos character will be the character located 
immediately before the start of the gap. If the cursor is 
narrow, or if the eos character is the last character in a range 
of locked text, AND if the bos character is not a bare accent 
character, the string will be inserted before the bos character. 
This means that the bos character must become the eos character 
and be moved to the other side of the gap: 



narrowcursor? 
eos eor = or 

gap prevchar c@ bare? not and 
if 

{ Make bos character the eos character ) 

( and move it to the other side of the gap. ) 

then 
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After the above test has been made, and the gap moved if 
necessary, the string is ready to be inserted. The selection is 
reset if necessary and the string is inserted starting at the gap 
location. If the character immediately before the gap was a bare 
accent, and if the first character in the inserted string is a 
character which may accept an accent, the two characters are 
swapped and turned into a real accented character pair. The gap 
position is incremented to just beyond the end of the inserted 
string and the text is marked as dirty. 



6.0.3 Redisplaying the Text 

After the text has been inserted, the bos pointer is reset: 

gap prevchar bos to 

the screen contents are redrawn as necessary: 

redisplay 

and the cursor is set to the wide cursor state. 
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6.1 ERASING TEXT 



The Erase command is associated with the Erase key. Erase always 
removes whatever character or characters are in the highlight and 
no others, with one exceptional case noted below. 

Backward erase : This is a form of character-by-character erasure 

which resembles backspacing on a typewriter. When the cursor is 
wide before an erasure, it will be wide on the character 
preceding the erased selection afterward. Thus the wide cursor 
removes text to its left or backward a character at a time. 

Forward erase or " gobble” : This, too, is a form of 

character-by-character erasure, useful in removing text to the 
cursor's right. If the cursor is narrow, Erase removes the 
character immediately underneath it, then replaces the missing 
character with the next character to the right. The cursor 
doesn't change or move, so, with repeated applications, it 
appears to be standing still while ''gobbling" the text to its 
right . 

Extended erase : When the highlight is extended, all the 

highlighted characters will be erased. The cursor will be left 
wide on the character preceding the erased selection. 

Erase turnaround : The first or last document break in the text 

or local leap region are exceptional cases. If Erase is invoked 
when the cursor is on the first document character in the text 
(or local leap region), that character will not be erased, but 
the cursor will become narrow on the next character forward. If 
the cursor is on the last document break in the text (or leap 
region), that character is not erased, but the cursor becomes 
wide on the character immediately preceding it. This is called 
erase turnaround because it switches a forward-erasing cursor to 
backward-erase, and vice versa. 



6.1.0 Preparing for Text Removal 

Before text can be removed, three tests must be made: 

1. Is the selection within a valid text range? 

2. Is the selection within a locked range of text? 

3. Does Erase undo preparation need to be performed? 
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trimselection makes sure the selection lies within a valid text 
range. If the user has used the Local Leap keys to reduce their 
working text area to a subset of the entire text, erasures can 
only occur within the local leap region of text. A local leap 
region of text will always be bounded on both sides by document 
characters, trimselection checks to see if the current selection 
flows over or includes either of the bounding document separator 
characters for the current local leap region and "trims" away any 
part of the selection which does not lie inside of the local leap 
region. If the entire selection lies outside of the local leap 
region, trimselection will return a false flag to indicate that 
the Erase operation cannot continue. 

Next, Erase checks to see if any part of the selection lies in a 
locked region of text. If any part of the selection is locked, 
the Erase operation is aborted, a warning beep is sounded, and an 
Explain message is made available. 

If the first two tests above were passed, the Erase operation 
will occur. First though, Erase checks to see if any undo 
preparation is required. If the previous operation was not an 
Erase operation, undo preparation must be performed. This 
involves clearing out the undo buffer (with clearundo) , saving 
the current cursor state (with savepos) , and clearing the 
contents of the format packet scratch area (by filling workpkt 
with zeros). If the previous operation was Erase, these undo 
preparations will have already been performed. 

Now we’re ready to Erase. The text is marked as dirty 
(dirtytext? on) and the state of the cursor is checked. If the 
cursor is narrow, gobble will be used. Otherwise, 
removeselection will be used to remove text. 



6.1.1 Gobbling Text 

6. 1.1.0 Checking the Selection Length 

gobble is the word used to remove the selection under the narrow 
cursor. The ' ble below shows the possible contents and lengths 
of a selection under a narrow cursor: 



Selection 



Selection Contents (Size) 



Normal Character 



ASCII code (1 byte) 



Accented Character 



ASCII code for character plus 
ASCII cod: for accent (2 bytes) 



Attributed Character 



ASCII code for character plus 
code for attribute (2 bytes) 



Accented attributed 
Character 



ASCII code for character, plus 
code for attribute, followed by 
ASCII code for accent 
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Carriage return 



ASCII code for CR plus paragraph 
format packet (1 + paragraph 
format packet length) 

Document Separator ASCII code for document separator 

plus document format packet plus 
paragraph format packet. (1 + 
document format packet length + 
paragraph format packet length) 

gobble checks for a selection length of less than 1 byte. The 
only time a narrow cursor’s selection length can be less than 1 
byte is when the narrow cursor is positioned over the last 
document character in the text. Since the last document 
character cannot be erased, gobble responds to this situation by 
moving the bos back by one character and resetting the cursor to 
a wide state. That way, if the ERASE key is pressed again, the 
erasing will proceed backwards in the text, away from the end of 
the text document character. After the bos has been 
repositioned, redisplay redraws the necessary parts of the text: 



{ Is the selection length less than 1? ) 

( Move the bos back by one character. ) 

( Redraw the screen contents. ) 

( Make the cursor wide instead of narrow. ) 
( Exit gobble immediately. ) 



selsize 1 < 
if 

eos prevchar bos to 

redisplay 

widecursor 

exit 

then 



6. 1.1.1 The Relationship Between Break Characters, Paragraph 
Format Packets, and the Text 



As you may recall from the section on ’’What's In the Text," 
paragraph format packets can only reside next to break characters 
(carriage return, page break or document separator) in the text. 

A paragraph format packet controls the appearance of all text 
following it up to the next occurrence of a break character 
followed by a paragraph format packet. A paragraph format 
packet, and the break character immediately following the text 
which the paragraph format packet controls, are invisibly linked 
to each other. The diagram on the following page illustrates 
this relationship between paragraph format packets, break 
characters, and the text. As you can see, the paragraph format 
packet and its associate break character lie on opposite ends of 
the text they control . 

The confusing part about this arrangement is that when a break 
character is selected, any paragraph format information following 
it is also included in the selection. But the paragraph format 
information following a break character is not the paragraph 
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format information with which the break character is associated, 
it is the paragraph format information which controls the 
following paragraph! 

As an example, refer to the left portion of diagram 6.1 on the 
following page. The carriage return following paragraph "1" has 
been selected for erasure. This means that both carriage return 
"1” and paragraph format packet "2" are included in the 
selection. We cannot simply dispose of the selection (paragraph 
format packet ”2" is not associated with carriage return "1"), 
nor can we remove only the carriage return (paragraph format 
packets must always be located after a break character) . The 
solution is to remove carriage return "1" and to move paragraph 
format packet "2" immediately after the previous break character 
in the text, carriage return ”0". 

In this example, since the carriage return being removed (#1) was 
also associated with a paragraph format packet (#1), paragraph 
format packet ”2" will be moved into the location previously 
occupied by paragraph format packet ”1” (which becomes invalid 
once its corresponding carriage return is erased) . If carriage 
return 1 had not been associated with a paragraph format packet, 
paragraph format packet ”2” would still have been moved after 
carriage return "0". The difference is that in the second case a 
space would have to made in the text after carriage return "0" 
for the insertion of paragraph format packet "2". 



- 109 - 




6.1 Gobbling a Carriage Return 
(and replacing its associated format packet) 



□□ 





/VvVuWvVvVw^^ 
vIVVvVvWVv^^ 



mm 



/V«/kAvVk/\VWV^ 

*1 s'c s > •■ ■< 'sj ^$0 5 "'Jy, ;■' v .> A' : 






/l44vWvVlVu^^ 

/VwVvVvVl/V^^^ 

/WlA/VvVlAvVvWVvV^ 



iUd] 



2 : 

/VvVvtvVv'V*^^ 

/VvVVVVlA/WW^^ 

/VvWWtvVt^ 

AvMvMvWVvVi^v^ 

/Vv^AvVUVV^VVl^^ 

? J 1 AvVvivVsAvWv :; . ; i ,i 11 



/VVMvVvVvMvV^^ 

/Vvhwvmvwv^ 

>VvVvWV\Av1a/V^ 



Carriage return 1 is tied to 
paragraph format packet 1 
which controls the appearance 
of paragraph 1 . If carriage 
return 1 is removed, 
paragraph format packet 1 
must be replaced with the 
next successive paragraph 
format packet, packet 2. 



After carriage return 1 and 
paragraph format packet 1 
have been removed, the 
previous paragraph 1 text 
is merged with the paragraph 
2 text. This larger paragraph 
2 is controlled by paragraph 
format packet 2. 
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6. 1.1. 2 Checking for Format Packets in the Selection 



Once gobble has checked the selection length, it uses pktbytes to 
check for paragraph format packets in the selection. The value 
returned by pktbytes, which is the number of paragraph format 
packet data bytes found in the specified region, is stored in the 
system integer fmtchrs. If the selection does contain paragraph 
format information, gobble is about to erase a break character. 
This means the break character, and its associated paragraph 
format packet, if any, must be removed and the paragraph format 
packet contained in the selection must be moved to a location 
immediately after the previous break character. This is the code 
that handles paragraph format packets in selections to be gobbled: 



bos gap pktbytes dup fmtchrs to ( Any format packets in selection? ) 
if 

workpkt $ 0= 
if 

bos findchar ( Save the current paragraph format ) 

workpkt makepkt ( packet state in the workpkt. ) 

then 

( Does the break being removed have an associated format packet? ) 

( Remember, the packet associated with the break being removed will ) 
( be located after the previous break in the text. ) 
bos prevbrk dup fpkt? 0= 
if 

brk+ pktsize makespace 1- ( If not, make room after the ) 

( previous break for the insertion ) 

( of a format packet.) 

then 

( Place a copy the packet contained in the selection after the ) 

( previous break in the text. ) 

bos swap copypkt 

then 



Note that if the scratch workpkt contains no data, the state of 
the paragraph which the break character follows is calculated and 
stored in the workpkt. 

6. 1.1.3 Finishing Up the Gobble 

Once any format packets have been handled, gobble is almost 
finished, findcalc and linkcalc find any Calc packets in the 
selection and to append them to a linked list (see the Calc 
discussion) . killivls marks all intervals which correspond to 
the selection for updating, partknown marks the second text 
partition -- all text after the selection -- as partially valid, 
movetext appends the selection to the end of the current undo 
buffer contents. The first character after the selection, the 
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character at the beot location, is moved to the front of the gap 
and is made the bos character -- it becomes the next character 
under the narrow cursor (gobble is marching forward in the 
text) . aftererase redraws the display, narrowcursor keeps the 
cursor narrow and ungobble is set as the undo operation for 
gobble. 

6.1.1.^ Undoing a Gobble 

ungobble is the undo operation for gobble, ungobble takes text 
out of the undo buffer and places format packets back in the text. 

If the workpkt contains paragraph format information, and the 
previous break in the text contains a format packet, the format 
packet in the workpkt is copied over the format packet at the 
previous break. If the previous break does not contain a format 
packet, no action is taken. Next, findcalc and unlinkcalc unlink 
all of the Calc packets which were linked by Erase (or regobble, 
see below) . killivls marks all intervals which correspond to the 
selection for updating, partknown marks the second text 
partition, all text after the selection, as partially valid. 

Now the contents of the undo buffer must be moved back into the 
text at the bos position. This is a three step process. First, 
the current bos character must be moved to the other side of the 
gap. Second, the first character in the undo buffer must be 
moved from the undo buffer to a location right before the front 
of the gap. Finally, the rest of the characters in the undo 
buffer must be moved to the far side of the gap. After these 
movements occur, the character before the gap is made the bos 
character and the first character after the gap is made the beot 
character. 

The remaining operations of ungobble involve using clearundo to 
clear the undo buffer, using aftererase to redraw the display, 
using narrowcursor to set the cursor to a narrow state, and 
setting regobble as the undo operation. 

6 . 1 . 1 . 5 Undoing an Ungobble 

regobble is the undo operation for ungobble. The first time the 
Undo key is pressed after an ERASE operation, an ungobble 
occurs, ungobble and regobble will alternate with each 
subsequent press of the Undo key. ungobble will always place 
everything in the undo buffer back into place in the text and 
regobble will always place the entire selection into the undo 
buffer. 

6. 1.1. 6 Removing a Selection 

If the cursor is wide or extended when Erase is used, all text 
within the selection will be removed. The cursor moves backwards 
in the text when Erase is used in this manner. The two words 
used to implement this type of erasing are <removeselection> and 
removeselection. See the definitions of these words for further 
information. 
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6.2 COPYING TEXT 



The Copy command is very similar to the part of Insert which 
actually places a small section of text into the larger text 
area. The words used to implement the Copy command are Copy, 
insertcopy, <insertcopy> , and Uncopy. 

Copy makes a copy of the current selection and tries to insert 
the copy into the text immediately after the end of the 
selection. Copy first checks the beginning and end of the 
selection to handle selections which may start or end on Calc 
packets or which lie at the beginning or end of a Leap range. 
After the selection endpoints have been adjusted, Copy checks to 
see if a valid selection is still left and exits if not. 
selected redisplays the adjusted selection. Copy also checks to 
make sure there is enough room for the selection and exits if 
not. At this point, the procedure used to copy the selection 
depends upon whether the selection to be copied lies within a 
locked document. If the selection is not locked, insertcopy 
places a copy of the selection in the gap, immediately after the 
skip information, insertcopy is then used to insert the copy 
into the text, immediately before the gap. 

If the selection is fully or partially locked, the copy must be 
placed immediately after the last document in the locked region. 
Copy checks to see where the last locked document ends and checks 
to see if there is any unlocked text following the last document. 

Once the destination for the copied text is determined, 
insertcopy places a copy of the selection in the gap. killivls 
marks all intervals in the insertion area as altered, 
insertblock actually inserts the copy into the text. 
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6.3 ROUTINES SUMMARY 



6.3.0 Insert Routines 



continueinsert? { -> c -1 ) if key is available 

( -> 0 ) if key is not available 

( pronounced kahn-tin*yu in’surt kwes'chun ) 
Fetches a key from the keyboard queue. If the key is not a 
special key, a true flag and the key information are returned on 
the stack. 

enough text ( nl -> f | if result is true ) 

( nl -> n2 f | if result is false ) 

( pronounced e-nuff tekst' ) 

enoughtext checks the amount of memory available for text 
insertion (that is, the amount of room in the gap) to see if 
there is enough room for nl bytes to be inserted into the text. 
If there is enough room, a true (non-zero) flag is returned. If 
there is not enough room, the number of available bytes (n2) and 
a false flag (0) are returned, enoughtext uses this basic 
equation to determine the amount of available gap memory: 

available gap memory = bou gap 4 



Insert ( c -> ) 

( pronounced in-sert 1 ) 

Inserts characters into the text until there are no characters 
left to insert. 

insertblock ( a n -> ) 

( pronounced in-sert 1 blok 1 ) 

Inserts the string at address a of length n into the text. The 
text is inserted starting at the gap location. Before inserting 
the text, insertblock checks for a locked text or an empty text. 
If the text is locked, an error message will be issued and no 
characters will be inserted. If the text is empty, the editor 
will be initialized before the insertion. If the string is 
inserted, the text will be marked as changed. 

resetselection? ( -> f ) 

( pronounced ree'set sa-lek’shun kwes'chun ) 
Returns the flag held in the forceop integer and then places a 0 
in forceop. If the flag is true, typing should force movement of 
the op. 
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6.3-1 Erase Routines 



aftererase ( -> ) 

( pronounced af'tur ee-rays 1 ) 

Checks to see if the line which contains the first break before 
the bos is visible in the window. If it is, aftererase 
selectively updates the window table entries for the lines 
between and including the previous break line and the gapline. 
Later when redisplay is used, only these selectively updated 
lines will be redrawn. Otherwise, if the previous break line is 
not in the window, gapline is set to zero to cause redisplay to 
completely recalculate and redraw the window contents. 

Erase ( -> ) 

( pronounced ee-rays * ) 

Erase is the word executed when the ERASE key is pressed. Erase 
puts the £erase value in the curop system integer to identify 
itself as the current operation, trimselection ensures a valid, 
erasable selection exists and lockedtext? makes sure the 
selection is not part of a locked portion of text. Next, Erase 
checks to see if the undo buffer has already been initialized for 
an erase operation. If the value in curop (%erase) is equal to 
the value in lastop then the last operation was an erasure and 
the undo buffer does not require initialization. Otherwise, 
clearundo clears the undo buffer, savepos saves the current 
cursor state, and the work packet, workpkt, is filled with 
zeroes. This is a signal that the format state preceding the 
selection has not been calculated yet. After Erase has checked 
and handled any undo initialization required, the text is marked 
as dirty. Now Erase must determine which type of erase operation 
should be performed. If the cursor is narrow, gobble erases 
forward in the text. If the cursor is not narrow, 
removeselection removes whatever characters are in the current 
selection. After the correct text has been erased, the locations 
of the op and pop are checked. If either of them point into the 
gap area, they are changed to point to the current bos location. 

gobble ( -> ) 

{ pronounced gah* bl ) 

Used by Erase when the cursor is narrow. If there is no text in 
the selection when gobble is called, the cursor must be at the 
end of text. The bos is set to eos prevchar, the text is 
redisplayed, the cursor is set to wide, and gobble is exited. If 
there is valid text, gobble next checks for format packets in the 
selection. If there are format packets, and the workpkt is 
empty, the state at the bos creates a format packet in the 
workpkt. This occurs only the first time in a series of erase 
operations to optimize for speed. Then, the break prior to the 
selection start is checked for a format packet. If the prior 
break has no format packet, a space is created for the insertion 
of a format packet. Then, the format packet in the selection is 
copied over the format packet or format packet space at the 
previous break location, gobble then uses killivls to mark all 
intervals corresponding to the text range between bos and gap as 
invalid, uses partknown to mark all intervals corresponding to 
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all text after beot as partially known, moves the selection to 
the undo buffer, sets up the next character in the text as the 
new selection, uses aftererase to redraw the display, leaves the 
cursor narrow, and sets ungobble as the undo operation. 

move text ( al a2 n -> ) 

{ pronounced mopy’ tekst ) 

In general, movetext removes the text region which starts at 
address al and is n bytes in length from the text and insert it 
into the text starting at address a 2. movetext is primarily used 
for moving selections, which start at the bos location, to and 
from the undo buffer, which starts at the bou location. 

If text is not being moved between the bos and bou 
locations, movetext will first use enoughtext to make sure there 
is enough room for the move operation. If the destination 
address is in the second text partition, movetext will move 
enough text to create a hole which is n bytes in size, just 
before the destination address and then will update all pointers 
affected by the text movement. If the destination is in the first 
text partition, room for the new text is created by moving the 
gap pointer position ahead by n bytes. 

Now that space has been created for the text, move moves the 
text into place. Next, movetext takes care of closing up the 
hole created in the text when the source text was removed. If 
the source text was located in the second text partition move 
closes up the hole and all pointers affected are updated. If the 
source text was in the first text partition the hole is closed up 
by simply reducing the gap pointer by n bytes, preset resets the 
gap skip markers . 

regobble ( -> ) 

( pronounced ree * gah ' bl } 

The undo operation for ungobble. 

removeselection ( -> ) 

( pronounced ree-moov 1 sa-lek'shun ) 

First uses <removeselection> to check the selection, link the 
calcs in the selection, and to handle any format packets in the 
selection. If <removeselection> returns the false flag that 
indicates that the erase process should continue, removeselection 
will move the selection to the undo buffer, set bos and epos 
equal to gap prevchar to reset the selection start, use 
aftererase to redraw the display, set the cursor to a widecursor, 
and make restoreselection the undo operation. 

<removeselection> ( -> f ) 

( pronounced brak'it ree-moov T sa-lek'shun ) 
Lower-level word called by removeselection. Returns a true flag 
if there is no valid text to erase or a false flag if the erase 
process should continue. <removeselection> first checks to see 
if there is any text in the selection. If there is text, but no 
text in the selection, then the cursor must be at the beginning 
of text. The cursor is made narrow and placed just after the 
bot, the text is redisplayed, and <removeselection> is exited. 

If the text and selection are both empty, the cursor is made 
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wide, placed at the beginning of the text, the text is 
redisplayed, and r removeselection> is exited. If the text or 
selection are not empty, <removeselection> links all Calc packets 
in the selection and checks to see if the selection contains any 
format packets. If there are no format packets in the 
selection, killivls marks the intervals corresponding to the bos 
through gap region for updating and partknown marks all of the 
text past the beot as partially known and <removeselection> is 
exited. If there is a format packet in the selection, 
<removeselection> exchanges the last format packet in the 
selection with the packet at the first break before the 
selection. The format packet at the first break before the 
selection is saved in the workpkt scratch area. All intervals 
corresponding to the bos prevbrk through gap region are marked 
for updating and all text past the beot is marked as partially 
known . 

restoreselection { -> ) 

{ pronounced ree-. ^r* sa-lek'shun ) 

This is the undo operation for removeselection . restoreselection 
moves the text in the undo buffer back into the text starting at 
the gap location and increments the gap and bou pointers by 
ubufsize bytes. If <removeselection> saved a packet in workpkt, 
restoreselection will place it back in the text after the break 
which immediately precedes the selection start, clearundo clears 
the undo buffer, the workpkt area is filled with zeros, all Calc 
packets in the selection are unlinked, all intervals between the 
break before the selection start and the selection end are marked 
for updating, the text after the beot is marked as partially 
known, the selection moved back into the text is reselected, the 
text is redisplayed, the cursor is made extended, and 
removeselection is set as the undo operation. 

trimselection ( -> f ) 

{ pronounced trim* sa-lek'shun ) 

If the selection begins on the document character that lies at 
either the start or end of the current local leap range, 
trimselection will ' f trim*’ the selection by bumping the start 
and/or end of selection forward/backward by one character. This 
is because the document characters which start and end the local 
leap range are not allowed to be erased or copied. Used by 
Erase. Returns a true flag if there is still a valid selection 
after trimming and a false flag if the selection contains no 
valid characters. If the only two characters in the selection 
region are the two document characters which mark the beginning 
and end of the current leap range, trimselection will return a 
false flag to indicate that there are no valid characters in the 
selection. 
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ungobble ( -> ) 

( pronounced un'gah’bl ) 

ungobble is the undo operation for gobble, ungobble first looks 
in workpkt to see if gobble removed a format packet. If workpkt 
holds a non-zero value, there is a format packet which needs to 
be put back into the text. If the first break before the bos has 
a format packet, the packet saved in workpkt will be copied over 
the current packet. If the prior break has no format packet, no 
action is taken. Next, unlinkcalc unlinks all selected Calc 
packets that must be placed back in the text {which currently 
resides in the undo buffer) . 



6.3-2 Copy Routines 

Copy ( -> ) 

( pronounced kali* pee ) 

Makes a copy of the current selection and tries to insert the 
copy into the text immediately after the end of the selection. 
Copy first checks the beginning and end of the selection to 
handle selections which may start or end on Calc packets or which 
lie at the beginning or end of a Leap range. After the selection 
endpoints have been adjusted, Copy checks to see if a valid 
selection is still left and exits if not. 

selected redisplays the adjusted selection. Copy also 
checks to make sure there is enough room for the selection, and 
exits if not. At this point the procedure used to copy the 
selection depends on whether the selection to be copied lies 
within a locked document. If the selection is not locked, 
insertcopy places a copy of the selection in the gap, immediately 
after the skip information. 

insertcopy is then used to insert the copy into the text, 
immediately before the gap. If the copy contains any paragraph 
formatting information, the format at the start of the copy must 
be preserved. If the break just before the copy contains a 
paragraph format packet, its contents are changed to match the 
formatting of the original. If the previous break has no format 
packet, a packet is inserted. If the selection is fully or 
partially locked, the copy must be placed immediately after the 
last document in the locked region. 

Copy checks to see where the last locked document ends and 
whether there is any unlocked text following the last document. 

If there is no unlocked text after the locked range, Copy issues 
an error End exits. If there is an unlocked area after the 
locked range, Copy proceeds with the copy process. 

insertcopy places a copy of the selection in the gap. 
killivls marks all intervals in the insertion area as altered, 
insertblock inserts the copy into the text, immediately before 
the gap, which has been repositioned to right after the locked 
text region. 

Now, Copy takes care of preserving formats. A format packet 
which reflects the original format of the text following the 
locked text region is created and either copied over a format 
packet that is before the copy or is inserted after the first 
break before the copy. 
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Likewise, a format packet which reflects the format at the 
beginning of the original selection is either copied over the 
first format packet after the copy or is inserted after the first 
break after the copy. <swappkt> is then used to swap the two 
packets so that both the copy and the text after the copy have 
the correct format. 

After the copy has been inserted into the text, the text and 
cursor are redisplayed, and Uncopy is set as the undo operation. 
Copy of unpocketed definitions (calc pocket) omits the expression 
starting at the colon to avoid duplicate definitions. Copy of 
pocketed calc pockets copies only surface text result and removes 
the dotted underline. 

<insertcopy> ( al a2 a3 -> al' a 2 f ) 

( pronounced brak’it in-sert* kah T pee ) 

Tries to copy the text bytes in the range from address al to 
address a^ to memory starting at address a 2. The copy process 
will stop if either (1) a document separator character is 
encountered, (2) a Calc packet is encountered, ( 3 ) the end 
address a^ is reached. The current locations of the source 
address al’ and destination address a2' are returned when 
<insertcopy> terminates. 

insertcopy ( al a2 n -> a2' ) 

{ pronounced in-sert 1 kah’pee ) 

Copies the n bytes located starting at address al to address a2 . 
Uses the lower level word <insertcopy> repeatedly to actually 
move the data. If <insertcopy> returns without having moved all 
of the data, then either a document separator or Calc token was 
encountered. If a document separator character was encountered, 
getdpkt reads the contents of the packet into the #ctrl array. 

The markbl value is stored in the #lock field to 
specifically mark the document as unlocked, makedpkt is then 
used to insert the modified document format packet into the copy 
and <insertcopy> is called again to continue moving the data 
after the document separator. If a Calc token was encountered, 
copypocket copies the Calc packet and <insertcopy> is called to 
continue moving the data after the Calc packet, insertcopy will 
continue calling <insertcopy> until all data has been moved. The 
address of the end of the copy is returned. 

Uncopy ( -> ) 

( pronounced un 1 kah-pee ) 

Uncopy uses <removeselection> to remove the copy, fixes the gap 
pointer, marks the text as dirty, makes Copy the undo operation, 
and redraw the display. 
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7. CHARACTER STYLE COMMANDS 



Introduction 



Three character style commands are available on the Cat: Bold , 

Underline t and Caps . All three affect the characters in the 
current selection. Bold and Underline affect the style/attribute 
byte which may or may not be associated with any character in the 
text (see "What's in the Text"). The Caps command affects only 
the ASCII value for the character. 
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7.0 PREPARING TO CHANGE THE CHARACTER STYLE 



Before any actions affecting the text are taken, the character 
style commands (Bold, Under, Caps) use extend to extend the 
selection and lockedsel to check whether the selection lies in a 
locked document. If any part of the selection lies in a locked 
document, the operation is aborted. 

After extending the selection and checking for locked text, the 
character style commands use these texts to see if undo 
preparation actions need to be taken. If any test is true, the 
character style commands will not initialize the undo buffer: 

1 . Is Uncfonnat the current undo operation? 

If Uncformat is the current undo operation, it means the user 
is trying to undo the affect of a previous character style 
command execution. The original selection affected by the 
character style command is already in the undo buffer. Undo 
buffer initialization is not required. 

2 . Does the undo buffer contain text or data? 

If the undo buffer contains text or data, if ubufsize returns 
a undo buffer length which is greater than zero, the undo 
buffer should not be initialized. 

3 . Is the Use Front key currently up? 

If the Use Front key is up, then the Undo key -- rather than 
the [Use Front] -[Character Style Command] key combination -- 
was used to execute this character style command. The 
original selection affected by the character style command is 
already in the undo buffer. Undo buffer initialization is 
not required. When a series of character style changes have 
been made. Undo will undo all of them, returning the text to 
the state it was in prior to any changes. 

If undo preparations are required, c : ; arundo will be used to 
clear out the undo buffer, selsize needtext will be used to check 
for memory availability, and cformatl will be used to copy the 
current, unstyled selection to the undo buffer. 
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7.1 TO STYLE OR NOT TO STYLE 



All of the character style commands are toggle commands. Each 
time a character style command is executed, it must either style, 
or unstyle the current selection. The action taken depends on 
the answers to the following questions: 

Should the selection be styled? 

Each of the character format commands analyzes the contents 
of the selection to determine if the selection should be 
styled or unstyled. 

The Bold and Underline commands check the following cases: 

1 . Can any of the characters in the selection receive an 
attribute? 

2 . Are there any characters in the selection which do not 
already have the chosen character style? 

If all printable characters in the selection are already bold or 
underlined when the command is given, the bold or underline 
attribute is removed from all of them. If any of the printable 
characters in the selection are not bold or underlined, they will 
become so when the command is given, that is, the attribute will 
be added to those characters and the rest will remain unchanged. 
Break characters and tabs do not take character attributes, and 
so are unaffected. Spaces are considered printing characters and 
do take character attributes. 

The Caps command performs one test: Are there any lowercase 

characters in the selection? 



If so, the entire selection should be capitalized. If all 
alphabetical characters are capitalized, they will be made 
lowercase . 

This logic does not apply in the case of a Learn command. If a 
Learn replay is in progress, the selection will always be styled 
on the first execution of the command, regardless of the 
foregoing set of rules. 

To understand why, imagine the following scenario: During the 

recording of a Learn sequence you press [Use Front]-[Bold] . The 
Cat assumes that your intention was to make the selected text 
bold, no matter what. By suspending the rule about making 
completely bold text plain, the Cat prevents you from 
inadvertently changing some previously bolded text into the 
opposite of what you intended when you designed the Learn 
sequence . 

The only way to cause a character format command to unstyle the 
text in a Learn sequence is to press the command key twice when 
you are recording the Learn sequence. 
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7.2 CHANGING THE CHARACTER STYLE 



Adding a character style attribute to each character in the 
selection is a four-step process: 

1. Determine how much extra memory will be required for the new 
attribute bytes. 

extramods looks through the selection and returns a count of 
how many new attribute bytes will be required. 

2. Check memory availability. 

There must be enough room in the gap for both the characters 
in the current selection and for all of the new attribute 
data. 

3. Move the selection into the gap area. 

4. Move the selection, with new attributes installed, back into 
the text. The phrase: 

gap extrasize + 5 + bos &uln movewith 

will move the selection characters, one-by-one, back into the 
text and will add the underline attribute to each character 
which requires it. 

Removing a character style attribute from each character in the 
selection is a three-step process: 

1. Check memory availability. There must be enough room in the 
gap for a copy of the selection. 

2. Move the selection into the gap area. 

3- Move the selection (with the attribute removed) back into the 
text. 

The phrase gap 5 + bos selsize $uln movenotwith will move the 
selection characters, one-by-one, back into the text and will 
remove the underline attribute from each character which 
possesses it. If the only attribute the character has is the 
underline attribute, movenotwith will remove the entire attribute 
byte. 

The words uppercase and lowercase are used by Caps to capitalize 
or lowercase the characters in a selection. 
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7.3 UNDOING A CHARACTER STYLE COMMAND 



All of the character style commands set Uncformat as their undo 
operation. 

Uncformat uses cformat3 to swap the current selection with the 
contents of the undo buffer, to set the new bou and bos values, 
to mark the intervals corresponding to the selection are for 
updating, and to redraw the display with the help of cformat2. 
Uncformat sets itself as the undo operation. 
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7.4 ROUTINES SUMMARY 



7.4.0 Bold and Underline Command Routines 



attribregion ( a nl n2 -> f ) 

( pronounced at'trib ree'jin ) 

Returns a true flag if any attributable character within the 
region of text of length nl which starts at address a does not 
yet have the attribute n2 . 

Bold ( -> ) 

( pronounced bohld’ ) 

Checks the current selection. The bold attribute will be removed 
from all characters in the selection if 

a. None of the characters in the selection can receive an attribute, OR 

b. If all of the characters in the selection already have the bold 
attribute, AND 

c. The current operation is the same as the last operation, OR 

d. A Learn activity is not occurring 

The bold attribute will be added to all characters in the 
selection if 

a. Any characters in the selection can receive an attribute, 

AND 

b. If there are characters in the selection that aren't bold, 

OR 

c. The current operation is not the same as the last operation, 

AND 

d. A Learn activity is occurring. 

Bold copies the current selection to the gap, then copies the 
selection back to the text, and inserts the bold character 
attribute at the same time. If the selection lies within a 
locked area of text or if there is not enough memory to create a 
copy of the selection, the operation will be aborted. If the 
selection is not already extended, it will be extended before the 
operation continues. 

Under ( -> ) 

( pronounced un* der ) 

Checks the current selection. The underline attribute will be 
removed from all characters in the selection if: 

a. None of the characters in the selection can receive an 
attribute, OR 

b. If all of the characters in the selection already have the 
underline attribute, AND 

c. The current operation is the same as the last operation, OR 

d. A Learn activity is not occurring 
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The underline attribute will be added to all characters in the 
selection if : 

a. Any characters in the selection can receive an attribute, AND 

b. If there are not-underlined characters in the selection, OR 

c. The current operation is not the same as the last operation, 
AND 

d. A Learn activity is occurring. 

Under copies the current selection to the gap, then copies the 
selection back to the text and inserts the underline character 
attribute at the same time. If the selection lies within a 
locked area of text or if there is not enough memory to create a 
copy of the selection, the operation will be aborted. If the 
selection is not already extended, it will be extended before the 
operation continues. 



7.4.1 Caps Command Routines 



capregion ( a n -> f ) 

( pronounced kap* ree'jin ) 

Returns a true flag if a lowercase character is found in the 
region of text of length n which starts at address a in the text. 



lowercase ( a n -> ) 

( pronounced lo'er kays ) 

Changes the n characters located in memory starting at address a 
to lowercase. 

Upper { -> ) 

( pronounced up 1 per ) 

Checks the current selection. All characters in the selection 
will be capitalized if : 

a. The selection contains one or more lowercase letters, OR 

b. The current operation is not the same as the last operation, 
AND 

c. A Learn activity is occurring 

All characters in the selection will be changed to lowercase if: 

a. The selection contains only capital letters, OR 

b. The current operation is the same as the last operation, AND 

c. A Learn activity is not occurring 

The routines uppercase and lowercase capitalize or lowercase the 
selection . 

uppercase ( a n -> ) 

( pronounced up 1 per kays ) 

Capitalizes the n characters located in memory starting at 
address a. 
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7.4.2 Words That Alter the Character Data 



extramods ( a nl ■> n2 ) 

( pronounced eks*tra mahds* ) 

Examines the nl bytes of text starting at address a and returns a 
count n 2 of how many characters within the range can be modified 
(can be underlined or boldfaced) . 

movewith ( al a2 nl n2 -> a3 ) 

{ pronounced moov with * ) 

Moves the nl bytes of text starting at address al to memory 
starting at address §2 and inserts the desired modifier 
information n2 after each character which can accept a modifier. 
Returns the address of the end of the newly modified selection. 

movenotwith ( al a2 nl n2 -> a3 ) 

( pronounced moov naht* with ) 

Moves the nl bytes of text starting at address al to memory 
starting at address §2. If a character has the modifier n2, the 
modifier is removed. If n2 was the only modifier appended to a 
character, the entire modifier byte is removed. Returns the 
address of the end of the newly modified selection. 

cforraatl ( -> ) 

( pronounced see for* mat wuhn ) 
"Character-format-one " prepares a selection for character 
modification. By repositioning the bou pointer, expands the undo 
buffer so that it is just large enough to hold the current 
selection. Moves the selection to the undo buffer. 

cformat2 ( a -> ) 

( pronounced see for* mat too ) 

Refreshes the selection after the characters in the selection 
have been modified. Updates the gap system integer with the 
address a which lies just after the last modified character. 
Recalculates the control/format information for those lines in 
the window record (which were affected by the character 
modification). Uses refresh to redraw the changed lines. Sets 
the cursor to "wide.” 

cfortnat3 ( -> ) 

( pronounced see for 1 mat three ) 

Places the modified selection text found in the undo buffer back 
in its previous spot in the text and uses cformat2 to update the 
display area containing the new text. 

Uncformat ( -> ) 

( pronounced un' see for* mat ) 

Calls cformat3 and makes itself the undo operation. 
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8. PARAGRAPH FORMAT COMMANDS 



Introduction 



There are six paragraph formatting operations: 

Left Margin 
Right Margin 
Indent 

Paragraph Style 
Line Spacing 
Set/Clear Tabs 

The shifted versions of these six, which restore the default 
setting for the corresponding format operation, make a total of 
12, Each operation changes either all paragraph format packets 
in the current selection or, if there is no selection, just the 
paragraph format packet which controls the paragraph which 
contains the cursor. The text is redisplayed to show the affects 
of the new paragraph format. 
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8.0 GENERAL DISCUSSION 



In order to change a particular aspect of a paragraph’s format, 
the corresponding field in the paragraph format packet which 
controls the paragraph must be changed and the display updated. 
The table below shows which paragraph format information fields 
in a control/format array are affected by each paragraph 
formatting command: 



Paragraph Format Field in Paragraph Format 

Operation Packet 



Line Spacing 
Left Margin 
Right Margin 
Indent 

Paragraph Style 
Set/Clear Tabs 



%lsp 

%left, &wide 
%wide, %iwide 
^indent, #iwide 
%just 
%tabs 



The six paragraph formatting commands are linked together so that 
as long as the Use Front key is held down several paragraph 
format commands may be used in succession without forcing the 
user to rehighlight the selection after each individual 
operation. When several commands are used in this manner, a 
single press of the Undo key will undo the effects of all of the 
commands . 



8.0.0 Paragraphs and Paragraph Format Packets 

A paragraph is defined as a group of characters which starts with 
the first character after a break character and ends with the 
following break character. The paragraph format packet which 
defines the format for a paragraph of text is located before the 
first character in the paragraph, immediately after the break 
character located at the end of the previous paragraph. Thus, 
when the format of a paragraph is changed, the previous paragraph 
format packet must be found and updated. If a paragraph does not 
have its own paragraph format packet, it is controlled by the 
first previous paragraph format in the text. 



8.0.1 The P aragraph Formatting Routines 

There are two versions of each of the six main paragraph 
formatting functions. The main version sets a format to the 
user’s specifications; the default version restores the default 
settings for the particular format operation. 
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Main Version 



Default Version 



Indent 

Justify 

Left 

Right 

Spacing 

Tabs 



Defindent 
Def justify 
Defleft 
Defright 
Defspacing 
Def tabs 



A table listing the default paragraph format settings for each 
country is included at the end of this section. 
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8.1 FOUR STEPS TO A NEW PARAGRAPH FORMAT 



The definition for the main version of the paragraph style 
command provides a general outline of the four steps required to 
change a paragraph format. 

Step 1 : Preparing the selection 

All of the paragraph formatting operations use preform for 
selection preparation purposes, preform checks for a locked 
selection and loads the current control/format information into 
the #ctrl array. 

Step 2: Getting the new format setting 

There are two methods used to determine new settings. The 
paragraph style and line spacing operations each allow only a 
small, fixed set of possible choices. Each time one of these 
operations is invoked it presents the user with the next 
available choice in its set. 

A new left/right margin, indent, or tab setting is chosen by 
the user with the aid of a graphical positioning tool. The 
listing below shows how the Justify command, a command with a 
fixed set of possible choices, performs step 2. 

Step 3« Saving the selection information 

The new format setting(s) was determined in Step 2. In Step 3, 
the new setting information is stored into the appropriate field 
in the ##ctrl array. 

Step 4: Updating the Text and the Display 

In Step 4, the formatting operations use reform to complete the 
formatting operation. In the exar le below, the token of 
fixjustify, which transfers the vaiue previously stored in the 
%just field of the ##ctrl array to the 2just field of the #ctrl 
array, is passed to reform, reform executes fixjustify, creates 
a paragraph format packet using the new paragraph format 
information in the #ctrl array, replaces all paragraph format 
packets in the selected area with the new format packet, and 
causes the screen to be redisplayed. 

The words fixspacing, fixindent, fixleft, fixright, and 
fixtabs perform functions similar to fixjustify for the other 
formatting operations. 
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Justify ( -> } 

preform 
#just c@ 2+ 
dup 4 = 
if 

drop 1 

then 
dup 5 = 
if 

drop 0 

then 

##ctrl %just ♦ c! 



[’] fixjustify reform 



{ 1. Prepare for formatting operation ) 

( 2. Calculate new format setting ) 

( Determine what the new value for the ) 
( paragraph style should be. ) 



( 3* Save new setting(s) info. ) 

( Store the new value in the $just ) 
{ field of the ##ctrl array. ) 

( 4. Update the text and selection ) 
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8.2 FOUR STEPS TO A DEFAULT PARAGRAPH FORMAT 



The definition for the default version of the paragraph style 
command provides a general outline of the four steps required to 
change a paragraph format. 



Defjustify, the default version of Justify, stores the default 
paragraph style setting found in an array of default paragraph 
format settings, in the ##ctrl, and then uses reform to finish 
the reformatting job. The default paragraph format settings are 
found in the #defaults array. 



: Defjustify { -> ) 

preform 

^defaults %just + c@ 
##ctrl %just + c! 

[ ' ] fixjustify reform 



( 1. Prepare for formatting operation. ) 
( 2. Calculate new format setting. } 

{ 3. Save new setting(s) information. ) 

( 4. Redisplay the selection. ) 
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8.3 OBTAINING NEW FORMAT SETTINGS 



The methods each paragraph format command uses to determine the 
user's new desired format setting are described below. 



8.3-0 Obtaining a New Line Spacing Setting 

The editor can handle three different line spacing settings: 



Line Spacing 



Field Value 



Single-spaced 2 
li -spaced 3 
Double-spaced 4 



Spacing calculates a new line-space setting by (1) obtaining the 
current line spacing value from the £lsp field in the #ctrl 
array, (2) adding 1 to the value, (3) subtracting 3 from the 
result if it is equal to 4. 



8.3-1 Obtaining a New Paragraph Style Setting 
The editor supports four paragraph styles: 



Paragraph Style Description Field Value 



Left- justified Justified left margin, ragged right 0 
Right- justified Justified right margin, ragged left 1 
Centered Ragged left and right margin 2 
Fully justified Justified left and right margin 3 



The paragraph style icons in the ruler display area are arranged 
from left to right as follows: Lef t- justif ied , Centered, 

Right-justified, Fully justified. 

When multiple selections of the paragraph style command are used, 
the icon highlight should flow smoothly from left to right, 
without skipping any icons. This means the %just field must be 
fed the following sequence of values: 0, 2, 1, 3 (refer to the 

table above). 

So, to calculate a new paragraph style value. Justify (1) obtains 
the current paragraph style value from the #just field of the 
#ctrl array, (2) adds 2 to the value, and (3) if the result is 4 
(invalid) sets the result to 1, or, if the result is 5 (invalid), 
sets the result to 0. 



- 134 - 




8.3-2 The Vertical Formatting Bar 

The left/right margin, indent, and tab commands use a graphical 
aid — a vertical formatting bar -- to help the user select new 
settings. After the user chooses one of these commands, the 
vertical bar appears on the screen in a command-specific location. 

At this point the command will wait in a loop, moving the 
vertical bar according to the user's inputs, until either an 
invalid key is pressed or until the Use Front key is released. 

An invalid key is any other paragraph formatting command key 
aside from the command key which caused the loop to be entered. 

So, as long as the Use Front key is depressed and an invalid key 
is not entered, the vertical bar will remain on the screen and 
the command word will be watching for positioning directions. 



8.3.3 Obtaining a New Left/Right Margin or Indent Setting 

If the left/right margin or indent commands are chosen, the word 
marginloop will be used for vertical bar positioning. While 
marginloop runs, it watches for presses of either Leap key. When 
the left or right Leap key is pressed, the vertical bar is moved 
one ruler increment to the left or right, selected fields in the 
#ctrl array are updated, and the ruler is redrawn to reflect the 
new left/right margin or indent position. 

When the Left Margin command is used, the *left, £wide , ^indent, 
and Jtiwide fields must be updated after each movement of the 
vertical bar. When the Right Margin command is used, the %wide 
and Jtiwide fields must be updated after each vertical bar 
movement. When the Indent command is used, the ^indent and 
%iwide fields must be updated with each movement. 



8 . 3 .^ Obtaining New Tab Settings 

When the tab command is chosen, the word tabloop is used for 
vertical bar positioning. While tabloop runs, it watches for six 
keys, and begaves as follows when they are pressed: 



Key 

Left Leap 
Right Leap 



Action 

Vertical bar moves one ruler increment to the left. 
Vertical bar moves one ruler increment to the right. 



Tab May either set, change, or remove a tab at the 

current Shift-Tab vertical bar location. The %tabs 
field in the #ctrl array is updated and the ruler 
redrawn . 



- 135 - 




Space 



The vertical bar is positioned at the next tab stop 
to the right of its current position. If there are 
no tabs to the right, the vertical bar will wrap 
around to the leftmost tab stop. If there are no 
tabs at all, the vertical bar will not be moved. 

Erase All of the tab stops are removed. 



Example of a Command That Uses the Vertical Bar 



The definition of Left shows the construction of a paragraph 
format command which uses the vertical format bar for new format 
selection: 



: Left ( -> ) 

preform ( 1. PREPARE FOR FORMATTING OPERATION. ) 

%setl curop to ( Set the current operation. ) 

( uses curop to check for valid keys ) 

( received. ) 

2 ( leftmost position for vertical bar ) 

#left c@ #wide c@ ♦ 2/ { rightmost position for vertical bar ) 

^indent c@ 2/ 2+ ( initial position for vertical bar ) 

initset ( Initialize integers used by ) 

{ marginloop.) 



marg inloop 



( Watch while the user chooses their } 
( settings. ) 



^indent c@ ##ctrl ^indent + c! ( Place new format info ) 
#lef t c@ ##ctrl %left ♦ c! ( in ##ctrl array. ) 

[*] fixindent reform ; ( Update the text and display. ) 



Refer to the routines summary, for more information on words used 
in the above listing. 
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8 . 4 PARAGRAPH FORMAT COMMANDS ROUTINES SUMMARY 



8.4.0 Words Used by Paragraph Format Commands 

Def indent ( -> ) 

( pronounced deff* in-dent ) 

Moves the default indent data from the ^defaults table to the 
##ctrl array and uses reform to reformat the entire selection 
according to the default indent setting. 

Defjustify { -> ) 

( pronounced deff* jus r ti-fy ) 

Moves the default paragraph style data from the ^defaults table 
to the ##ctrl array and uses reform to reformat the entire 
selection according to the default paragraph style setting. 

Def left ( -> ) 

( pronounced deff f left ) 

Moves the default left margin data from the ^defaults table to 
the ##ctrl array and uses reform to reformat the entire selection 
according to the default left margin setting. 

Defright ( -> ) 

( pronounced deff 1 ryt ) 

Moves the default right margin data from the ^defaults table to 
the ##ctrl array and uses reform to reformat the entire selection 
according to the default right margin setting. 

Def spacing ( -> ) 

( pronounced deff* spay 'sing ) 

Moves the default line spacing data from the ^defaults table to 
the ##ctrl array and uses reform to reformat the entire 
selection according to the default line spacing setting. 

Def tabs ( -> ) 

( pronounced deff 1 tabs ) 

Moves the default tab setting data from the #defaults table to 
the ##ctrl array and uses reform to reformat the entire selection 
according to the default tab settings. 

fixindent ( -> ) 

{ pronounced fiks* in-dent ) 

Transfers the contents of the ^indent field in the ##ctrl field 
to the ^indent field in the #ctrl array. Def indent and Indent 
pass the token of fixindent to reform which executes it once at 
each format packet location in the effectively modified range of 
text . 

fixjustify ( -> ) 

( pronounced fiks* jus-ti-fy ) 

Transfers the contents of the %just field in the ##ctrl field to 
the %just field in the #ctrl array. Defjustify and Justify pass 
the token of fixjustify to reform which executes it once at each 
format packet location in the effectively modified range of text. 
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fixlef t 



( -> ) 

( pronounced files* left ) 

Transfers the contents of the #left field in the ##ctrl field to 
the J£left field in the #ctrl array. Defleft and Left pass the 
token of fixlef t to reform which executes it once at each format 
packet location in the effectively modified range of text. 

fixright ( -> ) 

( pronounced fiks* ryt ) 

Transfers the contents of the fright field in the ##ctrl field to 
the fright field in the #ctrl array. Defright and Right pass the 
token of fixright to reform which executes it once at each format 
packet location in the effectively modified range of text. 

fixspacing ( -> ) 

( pronounced fiks* spay-sing ) 

Transfers the contents of the #lsp field in the ##ctrl field to 
the %lsp field in the #ctrl array. Def spacing and Spacing pass 
the token of fixspacing to reform which executes it once at each 
format packet location in the effectively modified range of text. 

fix tabs ( -> ) 

( pronounced fiks’ tabs ) 

Transfers the contents of the %tabs field in the ##ctrl field to 
the %tabs field in the #ctrl array. Def tabs and Tabs pass the 
token of fixtabs to reform which executes it once at each format 
packet location in the effectively modified range of text. 

Indent ( -> ) 

( pronounced in* dent ) 

Sets the current operation to £seti. Uses initset to set the 
iposit integer to the current indent location {^indent 
half-spaces), the rbound integer to the current right margin 
location {#left+#wide half-spaces) , the lbound integer to two 
half-spaces, and then sits in a loop, marginloop, and moves the 
indent line around while the user selects a new indent position. 
When the user has finished setting the indent position, Indent 
moves the new user indent data to the ##ctrl array and uses 
reform to reformat the entire selection according to the new 
indent setting. 

Justify ( -> ) 

{ pronounced .jus * ti-fy ) 

The paragraph style field in a control/format array, %just, can 
accept four values: 0 for Left-Justified , 1 for Right-Justified, 

2 for Centered, and 3 for Fully Justified. This field cycles 
between values in the following order: 

Before. . . After. . . 

0 -> 2 

2 -> 1 

1 -> 3 

3 -> 0 
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The new value is placed in the Jtjust field of the ##ctrl field, 
reform reformats the entire selection according to the new 
paragraph style setting. 

Left ( -> ) 

( pronounced left * ) 

Sets the current operation to %setl. Uses initset to set the 
iposit integer to the current left margin location (#left 
half-spaces) , the rboiind integer to the current right margin 
location (#left+#wide half-spaces) f the lbound integer to two 
half -spaces and then sits in a loop, marginloop, and moves the 
left margin line around while the user selects a new left margin 
position. When the user has finished setting the left margin, 
Left moves the new user left margin data to the ##ctrl array and 
uses reform to reformat the entire selection according to the new 
left margin setting. 

Right ( -> ) 

( pronounced ryt ' ) 

Sets the current operation to £setr. Uses initset to set the 
iposit integer to the current right margin location (#left+#wide 
half-spaces), the rbound integer to &horiz half-spaces, the 
lbound integer to either the left margin location (#left 
half-spaces) or the indent location (^indent half-spaces) , 
whichever is greater, and then sits in a loop, marginloop, and 
moves the right margin line around while the user selects a new 
right margin position. When the user has finished setting the 
right margin, Right moves the new user right margin data to the 
##ctrl array and uses reform to reformat the entire selection 
according to the new right margin setting. 

Spacing ( -> ) 

( pronounced spay sing ) 

The line-spacing field in a control/format array, $lsp, can 
accept three values: f, 2” for single-spaced text, "3” fen 

ll-spaced text, and ,, 4’ 1 for double-spaced text. The table below 
shows before and after values: 

Bef ore. . . After. . . 

2 -> 3 

3 -> 4 

4 -> 2 

Each time Spacing is executed, it takes the contents of the %lsp 
field in the #ctrl array and transforms it according to the 
pattern shown in the table above. The new value is stored in the 
Xlsp field of the ##ctrl field, reform then reformats the entire 
selection according to the new line spacing setting. 

Tabs { -> ) 

{ pronounced tabs * ) 

Sets the current operation to £sett. Uses initset to set the 
iposit integer to the ruler increment loca ion closest to the 
current cursor position, the rbound integer to 0 half-spaces, the 
lbound integer to 0 half-spaces. It then sits in a loop, 
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tabloop, and moves the vertical tab line around as the user sets 
up tab stops. When the user has finished setting tab stops, Tabs 
moves the new user tab data to the ##ctrl array and uses reform 
to reformat the entire selection according to the new user tab 
settings . 



8.4.1 Low-Level Paragraph Formatting Words 



^defaults ( -> a ) 

( pronounced sharp 1 dee 'f alts ) 

Pushes the address a of a table of default paragraph format 
settings on the stack. 

pformatl ( -> f> ) 

( pronounced pee 1 for 1 mat wun ' } 

Prepares the selection for a paragraph formatting operation by 
implacing paragraph format packets at the start and end of the 
selection, if necessary. A false flag means the operation was 
successful; a true flag means an error occurred. The steps in 
the execution of this word are as follows: 

1. Checks to see if there is enough room in the undo buffer to 
hold at least two paragraph format packets which the Cat 
needs to change the format state before and after the 
affected region. If there isn't enough room, pformatl exits 
immediately and returns a true flag. 

2. The format state before and after the selection must be found 
and saved so that it may be restored after the text in the 
selection has been formatted. The current state after the 
selection {which was previously found by preform) is saved 
into the workpkt scratch area. 

To find the previous format state, prevbrk and brk+ find 
the address of the first break (or first paragraph format 
packet) before the bos position, or before the bos nextchar 
position if the cursor is wide. The address is saved in the 
prepkt system integer. 

To find the format state after the selection, nextbrk 
and brk+ find the address of the first break (or paragraph 
format packet) after the beot prevchar position, or after the 
beot prevchar prevchar position if the cursor is is narrow. 
The address is stored in the postpkt system integer. 

3- Now pformatl checks both prepkt and postpkt to see whether 
they contain addresses of breaks or format packets. The 
address belongs to a paragraph format packet if the first 
byte at the address contains the paragraph format packet 
identification marker, &fmt. 

If the preceding break is not followed by a format 
packet, prepkt prevchar findchar gets the previous formatting 
state information and prepkt pktsize makespace makepkt 
encodes the information and insert the resulting format 
packet after the break. 

If the succeeding break is not followed by a format 
packet, postpkt prevchar findchar gets the formatting state 
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